fix: regenerate lockfile for spotlight notifications dependency

# Conflicts:
#	apps/nextjs/src/app/[locale]/manage/tools/docker/docker-table.tsx

.mise.toml

@@ -0,0 +1,3 @@
+[tools]
+node = "24.16.0"
+pnpm = "10.33.4"

apps/nextjs/package.json

@@ -18,6 +18,7 @@
     "@dnd-kit/modifiers": "catalog:",
     "@dnd-kit/sortable": "catalog:",
     "@dnd-kit/utilities": "catalog:",
+    "@gfazioli/mantine-onboarding-tour": "catalog:",
     "@homarr/analytics": "workspace:^0.1.0",
     "@homarr/api": "workspace:^0.1.0",
     "@homarr/auth": "workspace:^0.1.0",
@@ -56,6 +57,7 @@
     "@mantine/modals": "catalog:",
     "@mantine/tiptap": "catalog:",
     "@tabler/icons-react": "catalog:",
+    "@tanstack/query-persist-client-core": "catalog:",
     "@tanstack/react-query": "catalog:",
     "@tanstack/react-query-devtools": "catalog:",
     "@tanstack/react-query-next-experimental": "catalog:",

apps/nextjs/src/app/[locale]/_client-providers/query-cache-persister.ts

@@ -0,0 +1,49 @@
+import type { AsyncStorage, PersistedQuery } from "@tanstack/query-persist-client-core";
+import { experimental_createQueryPersister } from "@tanstack/query-persist-client-core";
+import { parse, stringify } from "superjson";
+
+import { fetchApi } from "@homarr/api/client";
+import {
+  getActiveQueryCacheBoardId,
+  isPersistableWidgetQueryKey,
+  queryCacheStoragePrefix,
+} from "@homarr/api/query-cache";
+
+const queryCacheStorage = {
+  async getItem(_key) {
+    return null;
+  },
+  async setItem(key, value) {
+    const boardId = getActiveQueryCacheBoardId();
+    if (!boardId) return;
+
+    try {
+      await fetchApi.queryCache.setItem.mutate({ boardId, key, value });
+    } catch {
+      // Query persistence is best-effort; failed writes should not affect widget rendering.
+    }
+  },
+  async removeItem(key) {
+    const boardId = getActiveQueryCacheBoardId();
+    if (!boardId) return;
+
+    try {
+      await fetchApi.queryCache.removeItem.mutate({ boardId, key });
+    } catch {
+      // Query persistence is best-effort; failed removals should not affect widget rendering.
+    }
+  },
+} satisfies AsyncStorage<string>;
+
+export const createWidgetQueryPersister = () =>
+  experimental_createQueryPersister<string>({
+    storage: typeof window === "undefined" ? undefined : queryCacheStorage,
+    maxAge: Number.POSITIVE_INFINITY,
+    prefix: queryCacheStoragePrefix,
+    refetchOnRestore: true,
+    serialize: (query) => stringify(query),
+    deserialize: (value) => parse<PersistedQuery>(value),
+    filters: {
+      predicate: (query) => isPersistableWidgetQueryKey(query.queryKey),
+    },
+  });

apps/nextjs/src/app/[locale]/_client-providers/trpc.tsx

@@ -19,9 +19,12 @@ import type { SuperJSONResult } from "superjson";
 
 import type { AppRouter } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
+import { queryCacheDefaultStaleTimeMs } from "@homarr/api/query-cache";
 import { createHeadersCallbackForSource, getTrpcUrl } from "@homarr/api/shared";
 import { env } from "@homarr/common/env";
 
+import { createWidgetQueryPersister } from "./query-cache-persister";
+
 const getWebSocketProtocol = () => {
   // window is not defined on server side
   if (typeof window === "undefined") {
@@ -49,12 +52,14 @@ const wsClient = createWSClient({
 });
 
 export function TRPCReactProvider(props: PropsWithChildren) {
+  const [queryPersister] = useState(() => createWidgetQueryPersister());
   const [queryClient] = useState(
     () =>
       new QueryClient({
         defaultOptions: {
           queries: {
-            staleTime: 5 * 1000,
+            persister: queryPersister.persisterFn,
+            staleTime: queryCacheDefaultStaleTimeMs,
           },
         },
       }),

apps/nextjs/src/app/[locale]/boards/(content)/_creator.tsx

@@ -1,10 +1,14 @@
+import { cache } from "react";
 import type { Metadata } from "next";
+import { Suspense } from "react";
 import { TRPCError } from "@trpc/server";
 
 // Placed here because gridstack styles are used for board content
 import "~/styles/gridstack.scss";
 
+import type { DehydratedState } from "@tanstack/react-query";
 import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
+import { parse } from "superjson";
 
 import { getQueryClient } from "@homarr/api/server";
 import { IntegrationProvider } from "@homarr/auth/client";
@@ -14,6 +18,7 @@ import { isNullOrWhitespace } from "@homarr/common";
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
 import type { WidgetKind } from "@homarr/definitions";
+import { getAllQueryCacheAsync } from "@homarr/redis";
 import { getI18n } from "@homarr/translation/server";
 import { prefetchForKindAsync } from "@homarr/widgets/prefetch";
 
@@ -34,17 +39,21 @@ interface Props<TParams extends Params> {
 export const createBoardContentPage = <TParams extends Record<string, unknown>>({
   getInitialBoardAsync: getInitialBoard,
 }: Props<TParams>) => {
+  const getCachedBoard = cache((_paramsKey: string, params: TParams) => getInitialBoard(params));
+  const getBoardForParams = (params: TParams) => getCachedBoard(JSON.stringify(params), params);
+
   return {
     layout: createBoardLayout({
       headerActions: <BoardContentHeaderActions />,
-      getInitialBoardAsync: getInitialBoard,
+      getInitialBoardAsync: getBoardForParams,
+      withTour: true,
     }),
     // eslint-disable-next-line no-restricted-syntax
     page: async ({ params }: { params: Promise<TParams> }) => {
       const resolvedParams = await params;
       const queryClient = getQueryClient();
 
-      const [board, session] = await Promise.all([getInitialBoard(resolvedParams), auth()]);
+      const [board, session] = await Promise.all([getBoardForParams(resolvedParams), auth()]);
 
       const itemsMap = board.items.reduce((acc, item) => {
         const existing = acc.get(item.kind);
@@ -71,9 +80,14 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
         ),
       ]);
 
+      const userId = session?.user.id ?? "anonymous";
+
       return (
         <HydrationBoundary state={dehydrate(queryClient)}>
           <IntegrationProvider integrations={integrations}>
+            <Suspense>
+              <QueryCacheHydration userId={userId} boardId={board.id} />
+            </Suspense>
             <DynamicClientBoard />
           </IntegrationProvider>
         </HydrationBoundary>
@@ -81,7 +95,7 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
     },
     generateMetadataAsync: async ({ params }: { params: Promise<TParams> }): Promise<Metadata> => {
       try {
-        const board = await getInitialBoard(await params);
+        const board = await getBoardForParams(await params);
         const t = await getI18n();
 
         return {
@@ -97,7 +111,6 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
           },
         };
       } catch (error) {
-        // Ignore not found errors and return empty metadata
         if (error instanceof TRPCError && error.code === "NOT_FOUND") {
           return {};
         }
@@ -107,3 +120,37 @@ export const createBoardContentPage = <TParams extends Record<string, unknown>>(
     },
   };
 };
+
+interface PersistedEntry {
+  state: { data: unknown; dataUpdatedAt: number; status: string };
+  queryKey: unknown[];
+  queryHash: string;
+}
+
+async function QueryCacheHydration({ userId, boardId }: { userId: string; boardId: string }) {
+  try {
+    const entries = await getAllQueryCacheAsync(userId, boardId);
+    const queries: DehydratedState["queries"] = [];
+
+    for (const serialized of Object.values(entries)) {
+      try {
+        const persisted = parse<PersistedEntry>(serialized);
+        if (persisted.state.status !== "success") continue;
+
+        queries.push({
+          state: persisted.state as DehydratedState["queries"][number]["state"],
+          queryKey: persisted.queryKey,
+          queryHash: persisted.queryHash,
+        });
+      } catch {
+        // skip malformed entries
+      }
+    }
+
+    if (queries.length === 0) return null;
+
+    return <HydrationBoundary state={{ mutations: [], queries }} />;
+  } catch {
+    return null;
+  }
+}

apps/nextjs/src/app/[locale]/boards/(content)/_header-actions.tsx

@@ -2,7 +2,8 @@
 
 import { useCallback, useEffect } from "react";
 import { useRouter } from "next/navigation";
-import { Group, Menu, ScrollArea } from "@mantine/core";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
+import { Box, Group, Menu, ScrollArea } from "@mantine/core";
 import { useHotkeys } from "@mantine/hooks";
 import {
   IconBox,
@@ -11,6 +12,7 @@ import {
   IconLayoutBoard,
   IconPencil,
   IconPencilOff,
+  IconPlug,
   IconPlus,
   IconReplace,
   IconResize,
@@ -36,6 +38,7 @@ import { useBoardPermissions } from "~/components/board/permissions/client";
 import { useCategoryActions } from "~/components/board/sections/category/category-actions";
 import { CategoryEditModal } from "~/components/board/sections/category/category-edit-modal";
 import { useDynamicSectionActions } from "~/components/board/sections/dynamic/dynamic-actions";
+import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
 import { HeaderButton } from "~/components/layout/header/button";
 
 export const BoardContentHeaderActions = () => {
@@ -53,9 +56,11 @@ export const BoardContentHeaderActions = () => {
 
       <EditModeMenu />
 
-      <HeaderButton href={`/boards/${board.name}/settings`}>
-        <IconSettings stroke={1.5} />
-      </HeaderButton>
+      <OnboardingTour.Target id="board-settings">
+        <HeaderButton href={`/boards/${board.name}/settings`}>
+          <IconSettings stroke={1.5} />
+        </HeaderButton>
+      </OnboardingTour.Target>
 
       <SelectBoardsMenu />
     </>
@@ -67,6 +72,7 @@ const AddMenu = () => {
   const { openModal: openCategoryEditModal } = useModalAction(CategoryEditModal);
   const { openModal: openItemSelectModal } = useModalAction(ItemSelectModal);
   const { openModal: openAppSelectModal } = useModalAction(AppSelectModal);
+  const { openModal: openIntegrationSelectModal } = useModalAction(IntegrationSelectModal);
   const { addCategoryToEnd } = useCategoryActions();
   const { addDynamicSection } = useDynamicSectionActions();
   const { createItem } = useItemActions();
@@ -108,6 +114,10 @@ const AddMenu = () => {
     });
   }, [openAppSelectModal, createItem]);
 
+  const handleAddIntegration = useCallback(() => {
+    openIntegrationSelectModal({});
+  }, [openIntegrationSelectModal]);
+
   return (
     <Menu position="bottom-end">
       <Menu.Target>
@@ -127,6 +137,10 @@ const AddMenu = () => {
           {t("app.action.add")}
         </Menu.Item>
 
+        <Menu.Item leftSection={<IconPlug size={20} />} onClick={handleAddIntegration}>
+          {t("integration.action.create")}
+        </Menu.Item>
+
         <Menu.Divider />
 
         <Menu.Item leftSection={<IconBoxAlignTop size={20} />} onClick={handleAddCategory}>
@@ -173,9 +187,11 @@ const EditModeMenu = () => {
   usePreventLeaveWithDirty(isEditMode);
 
   return (
-    <HeaderButton onClick={toggle} loading={isPending}>
-      {isEditMode ? <IconPencilOff stroke={1.5} /> : <IconPencil stroke={1.5} />}
-    </HeaderButton>
+    <OnboardingTour.Target id="board-edit-mode">
+      <HeaderButton onClick={toggle} loading={isPending}>
+        {isEditMode ? <IconPencilOff stroke={1.5} /> : <IconPencil stroke={1.5} />}
+      </HeaderButton>
+    </OnboardingTour.Target>
   );
 };
 
@@ -183,27 +199,31 @@ const SelectBoardsMenu = () => {
   const { data: boards = [] } = clientApi.board.getAllBoards.useQuery();
 
   return (
-    <Menu position="bottom-end">
-      <Menu.Target>
-        <HeaderButton w="auto" px={4}>
-          <IconReplace stroke={1.5} />
-        </HeaderButton>
-      </Menu.Target>
-      <Menu.Dropdown style={{ transform: "translate(-7px, 0)" }}>
-        <ScrollArea.Autosize mah={300}>
-          {boards.map((board) => (
-            <Menu.Item
-              key={board.id}
-              component={Link}
-              href={`/boards/${board.name}`}
-              leftSection={<IconLayoutBoard size={20} />}
-            >
-              {board.name}
-            </Menu.Item>
-          ))}
-        </ScrollArea.Autosize>
-      </Menu.Dropdown>
-    </Menu>
+    <OnboardingTour.Target id="board-switcher">
+      <Box>
+        <Menu position="bottom-end">
+          <Menu.Target>
+            <HeaderButton w="auto" px={4}>
+              <IconReplace stroke={1.5} />
+            </HeaderButton>
+          </Menu.Target>
+          <Menu.Dropdown style={{ transform: "translate(-7px, 0)" }}>
+            <ScrollArea.Autosize mah={300}>
+              {boards.map((board) => (
+                <Menu.Item
+                  key={board.id}
+                  component={Link}
+                  href={`/boards/${board.name}`}
+                  leftSection={<IconLayoutBoard size={20} />}
+                >
+                  {board.name}
+                </Menu.Item>
+              ))}
+            </ScrollArea.Autosize>
+          </Menu.Dropdown>
+        </Menu>
+      </Box>
+    </OnboardingTour.Target>
   );
 };
 
@@ -244,7 +264,7 @@ const usePreventLeaveWithDirty = (isDirty: boolean) => {
     };
 
     const handleBeforeUnload = (event: BeforeUnloadEvent) => {
-      if (env.NODE_ENV === "development") return; // Allow to reload in development
+      if (env.NODE_ENV === "development") return;
 
       event.preventDefault();
       event.returnValue = true;

apps/nextjs/src/app/[locale]/boards/_layout-creator.tsx

@@ -11,6 +11,7 @@ import { createLogger } from "@homarr/core/infrastructure/logs";
 import { MainHeader } from "~/components/layout/header";
 import { BoardLogoWithTitle } from "~/components/layout/logo/board-logo";
 import { ClientShell } from "~/components/layout/shell";
+import { BoardTourProvider } from "~/components/onboarding/board-tour";
 import { getCurrentColorSchemeAsync } from "~/theme/color-scheme";
 import type { Board } from "./_types";
 import type { Params } from "./(content)/_creator";
@@ -20,14 +21,21 @@ import { BoardMantineProvider } from "./(content)/_theme";
 
 const logger = createLogger({ module: "createBoardLayout" });
 
+const BoardTourWrapper = ({ hasSession, children }: PropsWithChildren<{ hasSession: boolean }>) => {
+  if (!hasSession) return <>{children}</>;
+  return <BoardTourProvider>{children}</BoardTourProvider>;
+};
+
 interface CreateBoardLayoutProps<TParams extends Params> {
   headerActions: JSX.Element;
   getInitialBoardAsync: (params: TParams) => Promise<Board>;
+  withTour?: boolean;
 }
 
 export const createBoardLayout = <TParams extends Params>({
   headerActions,
   getInitialBoardAsync: getInitialBoard,
+  withTour = false,
 }: CreateBoardLayoutProps<TParams>) => {
   const Layout = async ({
     params,
@@ -61,14 +69,16 @@ export const createBoardLayout = <TParams extends Params>({
           <EditModeProvider>
             <BoardMantineProvider defaultColorScheme={colorScheme}>
               <CustomCss />
-              <ClientShell hasNavigation={false}>
-                <MainHeader
-                  logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
-                  actions={headerActions}
-                  hasNavigation={false}
-                />
-                <AppShellMain>{children}</AppShellMain>
-              </ClientShell>
+              <BoardTourWrapper hasSession={withTour && !!session}>
+                <ClientShell hasNavigation={false}>
+                  <MainHeader
+                    logo={<BoardLogoWithTitle size="md" hideTitleOnMobile />}
+                    actions={headerActions}
+                    hasNavigation={false}
+                  />
+                  <AppShellMain>{children}</AppShellMain>
+                </ClientShell>
+              </BoardTourWrapper>
             </BoardMantineProvider>
           </EditModeProvider>
         </BoardReadyProvider>

apps/nextjs/src/app/[locale]/init/_components/init-step-card.tsx

@@ -0,0 +1,12 @@
+import type { PropsWithChildren } from "react";
+import { Card } from "@mantine/core";
+
+interface InitStepCardProps {
+  withBorder?: boolean;
+}
+
+export const InitStepCard = ({ children, withBorder = true }: PropsWithChildren<InitStepCardProps>) => (
+  <Card w="100%" withBorder={withBorder}>
+    {children}
+  </Card>
+);

apps/nextjs/src/app/[locale]/init/_constants.ts

@@ -0,0 +1,2 @@
+export const onboardingContentWidth = 64 * 16;
+export const onboardingMaxWidth = "90vw";

apps/nextjs/src/app/[locale]/init/_steps/finish/init-finish.tsx

@@ -1,39 +1,27 @@
 import type { MantineColor } from "@mantine/core";
-import { Button, Card, Stack, Text } from "@mantine/core";
-import { IconBook2, IconCategoryPlus, IconLayoutDashboard, IconMailForward } from "@tabler/icons-react";
+import { Button, Stack, Text } from "@mantine/core";
+import { IconBook2, IconLayoutDashboard, IconMailForward } from "@tabler/icons-react";
 
 import { isProviderEnabled } from "@homarr/auth/server";
 import { getMantineColor } from "@homarr/common";
-import { db } from "@homarr/db";
 import { createDocumentationLink } from "@homarr/definitions";
 import { getScopedI18n } from "@homarr/translation/server";
 import { Link } from "@homarr/ui";
 import type { TablerIcon } from "@homarr/ui";
 
+import { InitStepCard } from "../../_components/init-step-card";
+
 export const InitFinish = async () => {
-  const firstBoard = await db.query.boards.findFirst({ columns: { name: true } });
   const tFinish = await getScopedI18n("init.step.finish");
 
   return (
-    <Card w={64 * 6} maw="90vw">
+    <InitStepCard>
       <Stack>
         <Text>{tFinish("description")}</Text>
 
-        {firstBoard ? (
-          <InternalLinkButton
-            href={`/auth/login?callbackUrl=/boards/${firstBoard.name}`}
-            iconProps={{ icon: IconLayoutDashboard, color: "blue" }}
-          >
-            {tFinish("action.goToBoard", { name: firstBoard.name })}
-          </InternalLinkButton>
-        ) : (
-          <InternalLinkButton
-            href="/auth/login?callbackUrl=/manage/boards"
-            iconProps={{ icon: IconCategoryPlus, color: "blue" }}
-          >
-            {tFinish("action.createBoard")}
-          </InternalLinkButton>
-        )}
+        <InternalLinkButton href="/auth/login?callbackUrl=/" iconProps={{ icon: IconLayoutDashboard, color: "blue" }}>
+          {tFinish("action.goToBoard", { name: "dashboard" })}
+        </InternalLinkButton>
 
         {isProviderEnabled("credentials") && (
           <InternalLinkButton
@@ -51,7 +39,7 @@ export const InitFinish = async () => {
           {tFinish("action.docs")}
         </ExternalLinkButton>
       </Stack>
-    </Card>
+    </InitStepCard>
   );
 };
 

apps/nextjs/src/app/[locale]/init/_steps/group/init-group.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Button, Card, Stack, TextInput } from "@mantine/core";
+import { Button, Stack, TextInput } from "@mantine/core";
 import { IconArrowRight } from "@tabler/icons-react";
 import type { z } from "zod/v4";
 
@@ -10,6 +10,8 @@ import { useZodForm } from "@homarr/form";
 import { useI18n } from "@homarr/translation/client";
 import { groupCreateSchema } from "@homarr/validation/group";
 
+import { InitStepCard } from "../../_components/init-step-card";
+
 export const InitGroup = () => {
   const t = useI18n();
   const { mutateAsync } = clientApi.group.createInitialExternalGroup.useMutation({
@@ -34,7 +36,7 @@ export const InitGroup = () => {
   };
 
   return (
-    <Card w={64 * 6} maw="90vw">
+    <InitStepCard>
       <form onSubmit={form.onSubmit(handleSubmitAsync)}>
         <Stack>
           <TextInput
@@ -48,6 +50,6 @@ export const InitGroup = () => {
           </Button>
         </Stack>
       </form>
-    </Card>
+    </InitStepCard>
   );
 };

apps/nextjs/src/app/[locale]/init/_steps/import/file-info-card.tsx

@@ -1,10 +1,12 @@
-import { ActionIcon, Button, Card, Group, Text } from "@mantine/core";
+import { ActionIcon, Button, Group, Text } from "@mantine/core";
 import type { FileWithPath } from "@mantine/dropzone";
 import { IconPencil } from "@tabler/icons-react";
 
 import { humanFileSize } from "@homarr/common";
 import { useScopedI18n } from "@homarr/translation/client";
 
+import { InitStepCard } from "../../_components/init-step-card";
+
 interface FileInfoCardProps {
   file: FileWithPath;
   onRemove: () => void;
@@ -13,7 +15,7 @@ interface FileInfoCardProps {
 export const FileInfoCard = ({ file, onRemove }: FileInfoCardProps) => {
   const tFileInfo = useScopedI18n("init.step.import.fileInfo");
   return (
-    <Card w={64 * 12 + 8} maw="90vw" withBorder={false}>
+    <InitStepCard withBorder={false}>
       <Group justify="space-between" align="center" wrap="nowrap">
         <Group>
           <Text fw={500} lineClamp={1} style={{ wordBreak: "break-all" }}>
@@ -36,6 +38,6 @@ export const FileInfoCard = ({ file, onRemove }: FileInfoCardProps) => {
           <IconPencil size={16} stroke={1.5} />
         </ActionIcon>
       </Group>
-    </Card>
+    </InitStepCard>
   );
 };

apps/nextjs/src/app/[locale]/init/_steps/import/init-import.tsx

@@ -1,13 +1,14 @@
 "use client";
 
 import { startTransition, useState } from "react";
-import { Card, Stack } from "@mantine/core";
+import { Stack } from "@mantine/core";
 import type { FileWithPath } from "@mantine/dropzone";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
 import { InitialOldmarrImport } from "@homarr/old-import/components";
 
+import { InitStepCard } from "../../_components/init-step-card";
 import { FileInfoCard } from "./file-info-card";
 import { ImportDropZone } from "./import-dropzone";
 
@@ -20,7 +21,7 @@ export const InitImport = () => {
 
   if (!file) {
     return (
-      <Card w={64 * 12 + 8} maw="90vw">
+      <InitStepCard>
         <ImportDropZone
           loading={isPending}
           updateFile={(file) => {
@@ -40,12 +41,12 @@ export const InitImport = () => {
             });
           }}
         />
-      </Card>
+      </InitStepCard>
     );
   }
 
   return (
-    <Stack mb="sm">
+    <Stack w="100%" mb="sm">
       <FileInfoCard file={file} onRemove={() => setFile(null)} />
       {analyseResult !== null && <InitialOldmarrImport file={file} analyseResult={analyseResult} />}
     </Stack>

apps/nextjs/src/app/[locale]/init/_steps/integrations/docker-discovery-panel.tsx

@@ -0,0 +1,209 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import {
+  Avatar,
+  Badge,
+  Card,
+  Collapse,
+  Group,
+  Loader,
+  Paper,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Text,
+  ThemeIcon,
+  UnstyledButton,
+} from "@mantine/core";
+import { IconBrandDocker, IconCheck, IconChevronDown } from "@tabler/icons-react";
+
+import type { IntegrationKind } from "@homarr/definitions";
+import { getIntegrationName } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+import { IntegrationAvatar } from "@homarr/ui";
+
+export interface DiscoveredIntegration {
+  containerId: string;
+  containerName: string;
+  kind: IntegrationKind;
+  suggestedUrl: string;
+  publishedPort: number | null;
+  iconUrl: string | null;
+}
+
+export interface DiscoveredApp {
+  containerId: string;
+  containerName: string;
+  suggestedUrl: string;
+  publishedPort: number | null;
+  iconUrl: string | null;
+}
+
+interface DockerDiscoveryIndicatorProps {
+  integrations: DiscoveredIntegration[];
+  apps: DiscoveredApp[];
+  selectedAppIds: Set<string>;
+  onToggleApp: (containerId: string) => void;
+  isLoading: boolean;
+}
+
+const APP_CARD_HEIGHT = 80;
+
+export const DockerDiscoveryIndicator = ({
+  integrations,
+  apps,
+  selectedAppIds,
+  onToggleApp,
+  isLoading,
+}: DockerDiscoveryIndicatorProps) => {
+  const hasApps = apps.length > 0;
+  const [expanded, setExpanded] = useState(false);
+
+  const expandedOnce = useRef(false);
+  useEffect(() => {
+    if ((hasApps || integrations.length > 0) && !expandedOnce.current) {
+      expandedOnce.current = true;
+      setExpanded(true);
+    }
+  }, [hasApps, integrations.length]);
+
+  const t = useScopedI18n("init.step.integrations.docker");
+  const totalCount = integrations.length + apps.length;
+
+  if (!isLoading && totalCount === 0) return null;
+
+  const selectedAppCount = apps.filter((app) => selectedAppIds.has(app.containerId)).length;
+
+  if (isLoading) {
+    return (
+      <Paper
+        withBorder
+        p="sm"
+        radius="md"
+        style={{
+          borderColor: "var(--mantine-color-blue-4)",
+          background: "var(--mantine-color-blue-light)",
+        }}
+      >
+        <Group gap="sm" wrap="nowrap">
+          <ThemeIcon variant="light" color="blue" size="lg" radius="md">
+            <IconBrandDocker size={20} />
+          </ThemeIcon>
+          <Stack gap={0} style={{ flex: 1 }}>
+            <Text size="sm" fw={600}>
+              {t("scanning")}
+            </Text>
+            <Text size="xs" c="dimmed">
+              {t("scanningDescription")}
+            </Text>
+          </Stack>
+          <Loader size="sm" color="blue" type="dots" />
+        </Group>
+      </Paper>
+    );
+  }
+
+  return (
+    <Paper
+      withBorder
+      p="sm"
+      radius="md"
+      style={{
+        borderColor: "var(--mantine-color-blue-4)",
+        background: "var(--mantine-color-blue-light)",
+      }}
+    >
+      <UnstyledButton onClick={() => setExpanded((prev) => !prev)} w="100%">
+        <Group justify="space-between" wrap="nowrap">
+          <Group gap="sm" wrap="nowrap">
+            <ThemeIcon variant="light" color="blue" size="lg" radius="md">
+              <IconBrandDocker size={20} />
+            </ThemeIcon>
+            <Stack gap={0}>
+              <Text size="sm" fw={600}>
+                {t("detected", { count: String(totalCount) })}
+              </Text>
+              <Text size="xs" c="dimmed">
+                {t("detectedBreakdown", {
+                  integrations: String(integrations.length),
+                  apps: String(apps.length),
+                })}
+              </Text>
+            </Stack>
+          </Group>
+          <IconChevronDown
+            size={16}
+            color="var(--mantine-color-dimmed)"
+            style={{
+              transform: expanded ? "rotate(180deg)" : undefined,
+              transition: "transform 200ms ease",
+            }}
+          />
+        </Group>
+      </UnstyledButton>
+
+      <Collapse expanded={expanded}>
+        <Stack gap="xs" mt="sm">
+          {integrations.length > 0 && (
+            <Stack gap={4}>
+              {integrations.map((integration) => (
+                <Group key={integration.containerId} gap="xs" wrap="nowrap" py={2}>
+                  <IntegrationAvatar kind={integration.kind} size="xs" />
+                  <Text size="xs" fw={500} lineClamp={1} style={{ flex: 1, minWidth: 0 }}>
+                    {integration.containerName}
+                  </Text>
+                  <Badge size="xs" variant="light" color="blue">
+                    {getIntegrationName(integration.kind)}
+                  </Badge>
+                </Group>
+              ))}
+            </Stack>
+          )}
+
+          {hasApps && (
+            <Stack gap="xs">
+              <Text size="xs" fw={500}>
+                {t("appSectionLabel", { count: String(selectedAppCount) })}
+              </Text>
+              <ScrollArea.Autosize mah="30vh">
+                <SimpleGrid cols={{ base: 3, xs: 4, sm: 5 }} spacing="xs">
+                  {apps.map((app) => {
+                    const isSelected = selectedAppIds.has(app.containerId);
+                    return (
+                      <Card
+                        key={app.containerId}
+                        h={APP_CARD_HEIGHT}
+                        p="xs"
+                        withBorder
+                        style={{
+                          cursor: "pointer",
+                          borderColor: isSelected ? "var(--mantine-color-blue-6)" : undefined,
+                          borderWidth: isSelected ? 2 : undefined,
+                          opacity: isSelected ? 1 : 0.6,
+                        }}
+                        onClick={() => onToggleApp(app.containerId)}
+                      >
+                        <Stack justify="space-between" h="100%" gap={4} align="center">
+                          <Group justify="space-between" w="100%" wrap="nowrap">
+                            <Text size="xs" fw={500} lineClamp={1} style={{ flex: 1, minWidth: 0 }}>
+                              {app.containerName}
+                            </Text>
+                            {isSelected && <IconCheck size={14} color="var(--mantine-color-blue-6)" />}
+                          </Group>
+                          <Avatar size="sm" radius="sm" src={app.iconUrl} styles={{ image: { objectFit: "contain" } }}>
+                            {app.containerName.at(0)?.toUpperCase()}
+                          </Avatar>
+                        </Stack>
+                      </Card>
+                    );
+                  })}
+                </SimpleGrid>
+              </ScrollArea.Autosize>
+            </Stack>
+          )}
+        </Stack>
+      </Collapse>
+    </Paper>
+  );
+};

apps/nextjs/src/app/[locale]/init/_steps/integrations/init-integrations.tsx

@@ -0,0 +1,486 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import {
+  ActionIcon,
+  Alert,
+  Avatar,
+  Button,
+  Card,
+  Center,
+  Collapse,
+  Group,
+  Loader,
+  Paper,
+  Progress,
+  SegmentedControl,
+  SimpleGrid,
+  Stack,
+  Text,
+  TextInput,
+  ThemeIcon,
+  Tooltip,
+} from "@mantine/core";
+import { useDisclosure } from "@mantine/hooks";
+import {
+  IconAlertTriangle,
+  IconArrowRight,
+  IconBrandDocker,
+  IconCheck,
+  IconChevronDown,
+  IconSettings,
+} from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import type { IntegrationKind, UrlTemplateMode } from "@homarr/definitions";
+import { buildAppUrl, buildIntegrationUrl, getIntegrationName } from "@homarr/definitions";
+import { showErrorNotification } from "@homarr/notifications";
+import { useScopedI18n } from "@homarr/translation/client";
+import { IntegrationAvatar } from "@homarr/ui";
+
+import { NewIntegrationForm } from "~/app/[locale]/manage/integrations/new/_integration-new-form";
+import { IntegrationMultiSelectGrid } from "~/components/integration/integration-multi-select-grid";
+import { InitStepCard } from "../../_components/init-step-card";
+
+type Phase = "select" | "configure" | "done";
+
+interface IntegrationDraft {
+  kind: IntegrationKind;
+  initialUrl: string;
+  initialName?: string;
+  dockerPort?: number | null;
+  source: "manual" | "docker";
+}
+
+export const InitIntegrations = () => {
+  const [phase, setPhase] = useState<Phase>("select");
+  const [drafts, setDrafts] = useState<Map<IntegrationKind, IntegrationDraft>>(new Map());
+  const [selectedKinds, setSelectedKinds] = useState<IntegrationKind[]>([]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [baseHost, setBaseHost] = useState("");
+  const [urlMode, setUrlMode] = useState<UrlTemplateMode>("subdomain");
+  const t = useScopedI18n("init.step.integrations");
+  const router = useRouter();
+
+  const { mutateAsync: setupIntegrations } = clientApi.onboard.setupIntegrations.useMutation();
+  const { mutateAsync: createApps } = clientApi.onboard.createAppsFromDiscovery.useMutation();
+
+  const { data: dockerData, isPending: isDockerLoading } = clientApi.onboard.discoverDockerServices.useQuery(
+    undefined,
+    {
+      retry: false,
+      refetchOnWindowFocus: false,
+    },
+  );
+
+  const dockerIntegrations = dockerData?.status === "success" ? dockerData.integrations : [];
+  const dockerApps = dockerData?.status === "success" ? dockerData.apps : [];
+  const totalDetected = dockerIntegrations.length + dockerApps.length;
+
+  const detectedKinds = useMemo(
+    () => new Set(dockerIntegrations.map((i) => i.kind)),
+    [dockerIntegrations],
+  );
+
+  const [selectedAppIds, setSelectedAppIds] = useState<Set<string>>(new Set());
+  const [appsExpanded, setAppsExpanded] = useState(false);
+
+  const dockerApplied = useRef(false);
+  useEffect(() => {
+    if (dockerData?.status !== "success" || dockerApplied.current) return;
+    dockerApplied.current = true;
+
+    const newDrafts = new Map(drafts);
+    const newKinds = new Set(selectedKinds);
+
+    for (const item of dockerData.integrations) {
+      if (!newDrafts.has(item.kind)) {
+        newDrafts.set(item.kind, {
+          kind: item.kind,
+          initialUrl: item.suggestedUrl,
+          initialName: item.containerName,
+          dockerPort: item.publishedPort,
+          source: "docker",
+        });
+      }
+      newKinds.add(item.kind);
+    }
+
+    setDrafts(newDrafts);
+    setSelectedKinds(Array.from(newKinds));
+    setSelectedAppIds(new Set(dockerData.apps.map((app) => app.containerId)));
+    if (dockerData.apps.length > 0) {
+      setAppsExpanded(true);
+    }
+  }, [dockerData]);
+
+  const handleSelectionChange = useCallback((kinds: IntegrationKind[]) => {
+    setSelectedKinds(kinds);
+  }, []);
+
+  const handleToggleApp = useCallback((containerId: string) => {
+    setSelectedAppIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(containerId)) {
+        next.delete(containerId);
+      } else {
+        next.add(containerId);
+      }
+      return next;
+    });
+  }, []);
+
+  const handleContinueToConfig = () => {
+    const newDrafts = new Map(drafts);
+    for (const kind of selectedKinds) {
+      const existing = newDrafts.get(kind);
+      if (baseHost) {
+        newDrafts.set(kind, {
+          kind,
+          initialUrl: buildIntegrationUrl(kind, baseHost, urlMode, existing?.dockerPort ?? undefined),
+          initialName: existing?.initialName,
+          dockerPort: existing?.dockerPort,
+          source: existing?.source ?? "manual",
+        });
+      } else if (!existing) {
+        newDrafts.set(kind, { kind, initialUrl: "", source: "manual" });
+      }
+    }
+    setDrafts(newDrafts);
+    setCurrentIndex(0);
+    setPhase("configure");
+  };
+
+  const finishSetupAsync = async () => {
+    setPhase("done");
+    try {
+      const appsToCreate = dockerApps.filter((app) => selectedAppIds.has(app.containerId));
+      if (appsToCreate.length > 0) {
+        await createApps(
+          appsToCreate.map((app) => {
+            const href = baseHost
+              ? buildAppUrl(app.containerName, baseHost, urlMode, app.publishedPort ?? undefined)
+              : app.suggestedUrl;
+            return {
+              name: app.containerName,
+              href: href || null,
+              iconUrl: app.iconUrl,
+            };
+          }),
+        );
+      }
+      await setupIntegrations();
+      router.refresh();
+    } catch {
+      showErrorNotification({
+        title: t("configure.error.title"),
+        message: t("configure.error.message"),
+      });
+      setPhase("select");
+    }
+  };
+
+  const advanceOrFinish = () => {
+    if (currentIndex + 1 >= selectedKinds.length) {
+      void finishSetupAsync();
+    } else {
+      setCurrentIndex((i) => i + 1);
+    }
+  };
+
+  const backToSelect = () => {
+    setPhase("select");
+    setCurrentIndex(0);
+  };
+
+  if (phase === "done") {
+    return (
+      <InitStepCard>
+        <Center py="xl">
+          <Stack align="center" gap="md">
+            <Loader size="lg" />
+            <Text>{t("configure.finishing")}</Text>
+          </Stack>
+        </Center>
+      </InitStepCard>
+    );
+  }
+
+  if (phase === "configure") {
+    return (
+      <ConfigurePhase
+        selectedKinds={selectedKinds}
+        currentIndex={currentIndex}
+        drafts={drafts}
+        baseHost={baseHost}
+        setBaseHost={setBaseHost}
+        urlMode={urlMode}
+        setUrlMode={setUrlMode}
+        onSuccess={advanceOrFinish}
+        onCancel={backToSelect}
+        onSkip={advanceOrFinish}
+      />
+    );
+  }
+
+  const selectedAppCount = dockerApps.filter((app) => selectedAppIds.has(app.containerId)).length;
+
+  return (
+    <InitStepCard>
+      <Stack>
+        <Text>{t("description")}</Text>
+
+        <Alert variant="outline" color="orange" icon={<IconAlertTriangle />} title={t("urlTemplate.label")}>
+          <Stack gap="xs">
+            <Text size="sm" fw={500}>
+              {t("urlTemplate.warning")}
+            </Text>
+            <Group gap="sm" grow>
+              <TextInput
+                placeholder={t("urlTemplate.placeholder")}
+                value={baseHost}
+                onChange={(e) => setBaseHost(e.currentTarget.value)}
+                data-autofocus
+              />
+              <SegmentedControl
+                value={urlMode}
+                onChange={(value) => setUrlMode(value as UrlTemplateMode)}
+                data={[
+                  { label: t("urlTemplate.mode.subdomain"), value: "subdomain" },
+                  { label: t("urlTemplate.mode.hostPort"), value: "hostPort" },
+                ]}
+                style={{ flex: "0 0 auto" }}
+              />
+            </Group>
+            {baseHost && (
+              <Text size="xs" c="dimmed">
+                {t("urlTemplate.preview", { example: buildIntegrationUrl("sonarr", baseHost, urlMode) })}
+              </Text>
+            )}
+          </Stack>
+        </Alert>
+
+        {isDockerLoading && (
+          <Paper withBorder p="sm" radius="md">
+            <Group gap="sm" wrap="nowrap">
+              <ThemeIcon variant="light" color="blue" size="lg" radius="md">
+                <IconBrandDocker size={20} />
+              </ThemeIcon>
+              <Text size="sm" fw={500}>
+                {t("docker.scanning")}
+              </Text>
+              <Loader size="sm" color="blue" type="dots" />
+            </Group>
+          </Paper>
+        )}
+
+        {!isDockerLoading && totalDetected > 0 && (
+          <Paper withBorder p="sm" radius="md" style={{ borderColor: "var(--mantine-color-teal-4)" }}>
+            <Group gap="sm" wrap="nowrap">
+              <ThemeIcon variant="light" color="teal" size="lg" radius="md">
+                <IconBrandDocker size={20} />
+              </ThemeIcon>
+              <Text size="sm">
+                {t("docker.summary", {
+                  apps: String(totalDetected),
+                  integrations: String(dockerIntegrations.length),
+                })}
+              </Text>
+            </Group>
+          </Paper>
+        )}
+
+        <IntegrationMultiSelectGrid
+          selectedKinds={selectedKinds}
+          onSelectionChange={handleSelectionChange}
+          detectedKinds={detectedKinds}
+          onboarding
+        />
+
+        {dockerApps.length > 0 && (
+          <Paper withBorder p="sm" radius="md">
+            <Stack gap="xs">
+              <Group
+                justify="space-between"
+                wrap="nowrap"
+                style={{ cursor: "pointer" }}
+                onClick={() => setAppsExpanded((prev) => !prev)}
+              >
+                <Text size="sm" fw={500}>
+                  {t("docker.appSectionLabel", { count: String(selectedAppCount) })}
+                </Text>
+                <IconChevronDown
+                  size={16}
+                  color="var(--mantine-color-dimmed)"
+                  style={{
+                    transform: appsExpanded ? "rotate(180deg)" : undefined,
+                    transition: "transform 200ms ease",
+                  }}
+                />
+              </Group>
+              <Collapse expanded={appsExpanded}>
+                <SimpleGrid cols={{ base: 3, xs: 4, sm: 5 }} spacing="xs">
+                  {dockerApps.map((app) => {
+                    const isSelected = selectedAppIds.has(app.containerId);
+                    return (
+                      <Card
+                        key={app.containerId}
+                        h={80}
+                        p="xs"
+                        withBorder
+                        style={{
+                          cursor: "pointer",
+                          borderColor: isSelected ? "var(--mantine-color-blue-6)" : undefined,
+                          borderWidth: isSelected ? 2 : undefined,
+                          opacity: isSelected ? 1 : 0.6,
+                        }}
+                        onClick={() => handleToggleApp(app.containerId)}
+                      >
+                        <Stack justify="space-between" h="100%" gap={4} align="center">
+                          <Group justify="space-between" w="100%" wrap="nowrap">
+                            <Text size="xs" fw={500} lineClamp={1} style={{ flex: 1, minWidth: 0 }}>
+                              {app.containerName}
+                            </Text>
+                            {isSelected && <IconCheck size={14} color="var(--mantine-color-blue-6)" />}
+                          </Group>
+                          <Avatar size="sm" radius="sm" src={app.iconUrl} styles={{ image: { objectFit: "contain" } }}>
+                            {app.containerName.at(0)?.toUpperCase()}
+                          </Avatar>
+                        </Stack>
+                      </Card>
+                    );
+                  })}
+                </SimpleGrid>
+              </Collapse>
+            </Stack>
+          </Paper>
+        )}
+
+        <Group justify="space-between">
+          <Button variant="subtle" onClick={() => void finishSetupAsync()}>
+            {t("action.skip")}
+          </Button>
+          <Button
+            onClick={handleContinueToConfig}
+            disabled={selectedKinds.length === 0 || undefined}
+            rightSection={<IconArrowRight size={16} stroke={1.5} />}
+            suppressHydrationWarning
+          >
+            {t("action.continue")} {selectedKinds.length > 0 && `(${selectedKinds.length})`}
+          </Button>
+        </Group>
+      </Stack>
+    </InitStepCard>
+  );
+};
+
+interface ConfigurePhaseProps {
+  selectedKinds: IntegrationKind[];
+  currentIndex: number;
+  drafts: Map<IntegrationKind, IntegrationDraft>;
+  baseHost: string;
+  setBaseHost: (value: string) => void;
+  urlMode: UrlTemplateMode;
+  setUrlMode: (value: UrlTemplateMode) => void;
+  onSuccess: () => void;
+  onCancel: () => void;
+  onSkip: () => void;
+}
+
+const ConfigurePhase = ({
+  selectedKinds,
+  currentIndex,
+  drafts,
+  baseHost,
+  setBaseHost,
+  urlMode,
+  setUrlMode,
+  onSuccess,
+  onCancel,
+  onSkip,
+}: ConfigurePhaseProps) => {
+  const t = useScopedI18n("init.step.integrations");
+  const [helpersOpen, { toggle: toggleHelpers }] = useDisclosure(false);
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- currentIndex is always within bounds of selectedKinds
+  const currentKind = selectedKinds[currentIndex]!;
+  const draft = drafts.get(currentKind);
+  const progress = ((currentIndex + 1) / selectedKinds.length) * 100;
+  const computedUrl = baseHost
+    ? buildIntegrationUrl(currentKind, baseHost, urlMode, draft?.dockerPort ?? undefined)
+    : draft?.initialUrl;
+
+  return (
+    <InitStepCard>
+      <Stack>
+        <Group justify="space-between" align="center">
+          <Group gap="xs">
+            <IntegrationAvatar kind={currentKind} size="sm" />
+            <Text fw={500}>{getIntegrationName(currentKind)}</Text>
+          </Group>
+          <Tooltip label={t("configure.helpers.tooltip")}>
+            <ActionIcon variant={helpersOpen ? "light" : "subtle"} color="gray" onClick={toggleHelpers}>
+              <IconSettings size={18} stroke={1.5} />
+            </ActionIcon>
+          </Tooltip>
+        </Group>
+
+        <Stack gap={4}>
+          <Progress value={progress} size="sm" />
+          <Text size="xs" c="dimmed" ta="center">
+            {t("configure.progress", { current: String(currentIndex + 1), total: String(selectedKinds.length) })}
+          </Text>
+        </Stack>
+
+        <Collapse expanded={helpersOpen}>
+          <Stack
+            gap="xs"
+            p="xs"
+            style={{ background: "var(--mantine-color-default-hover)", borderRadius: "var(--mantine-radius-sm)" }}
+          >
+            <Text size="xs" c="dimmed">
+              {t("configure.helpers.description")}
+            </Text>
+            <Group gap="sm" grow>
+              <TextInput
+                size="xs"
+                placeholder={t("urlTemplate.placeholder")}
+                value={baseHost}
+                onChange={(e) => setBaseHost(e.currentTarget.value)}
+              />
+              <SegmentedControl
+                size="xs"
+                value={urlMode}
+                onChange={(value) => setUrlMode(value as UrlTemplateMode)}
+                data={[
+                  { label: t("urlTemplate.mode.subdomain"), value: "subdomain" },
+                  { label: t("urlTemplate.mode.hostPort"), value: "hostPort" },
+                ]}
+                style={{ flex: "0 0 auto" }}
+              />
+            </Group>
+            {baseHost && (
+              <Text size="xs" c="dimmed">
+                {t("urlTemplate.preview", {
+                  example: buildIntegrationUrl(currentKind, baseHost, urlMode, draft?.dockerPort ?? undefined),
+                })}
+              </Text>
+            )}
+          </Stack>
+        </Collapse>
+
+        <NewIntegrationForm
+          key={currentKind}
+          kind={currentKind}
+          initialUrl={computedUrl}
+          initialName={draft?.initialName}
+          onSuccess={onSuccess}
+          onCancel={onCancel}
+          onSkip={onSkip}
+          isOnboarding
+        />
+      </Stack>
+    </InitStepCard>
+  );
+};

apps/nextjs/src/app/[locale]/init/_steps/settings/init-settings.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Button, Card, Group, Stack, Switch, Text } from "@mantine/core";
+import { Button, Group, Stack, Switch, Text } from "@mantine/core";
 import { IconArrowRight } from "@tabler/icons-react";
 import type { z } from "zod/v4";
 
@@ -13,6 +13,8 @@ import type { TranslationObject } from "@homarr/translation";
 import { useI18n, useScopedI18n } from "@homarr/translation/client";
 import { settingsInitSchema } from "@homarr/validation/settings";
 
+import { InitStepCard } from "../../_components/init-step-card";
+
 export const InitSettings = () => {
   const tSection = useScopedI18n("management.page.settings.section");
   const t = useI18n();
@@ -29,8 +31,8 @@ export const InitSettings = () => {
 
   return (
     <form onSubmit={form.onSubmit(handleSubmitAsync)}>
-      <Stack>
-        <Card w={64 * 12 + 8} maw="90vw">
+      <Stack w="100%">
+        <InitStepCard>
           <Stack gap="sm">
             <Text fw={500}>{tSection("analytics.title")}</Text>
 
@@ -38,8 +40,8 @@ export const InitSettings = () => {
               <AnalyticsRow kind="general" {...form.getInputProps("analytics.enableGeneral", { type: "checkbox" })} />
             </Stack>
           </Stack>
-        </Card>
-        <Card w={64 * 12 + 8} maw="90vw">
+        </InitStepCard>
+        <InitStepCard>
           <Stack gap="sm">
             <Text fw={500}>{tSection("crawlingAndIndexing.title")}</Text>
 
@@ -62,7 +64,7 @@ export const InitSettings = () => {
               />
             </Stack>
           </Stack>
-        </Card>
+        </InitStepCard>
 
         <Button type="submit" loading={form.submitting} rightSection={<IconArrowRight size={16} stroke={1.5} />}>
           {t("common.action.continue")}

apps/nextjs/src/app/[locale]/init/_steps/start/init-start.tsx

@@ -1,16 +1,17 @@
-import { Card, Stack, Text } from "@mantine/core";
+import { Stack, Text } from "@mantine/core";
 import { IconFileImport, IconPlayerPlay } from "@tabler/icons-react";
 
 import { getMantineColor } from "@homarr/common";
 import { getScopedI18n } from "@homarr/translation/server";
 
+import { InitStepCard } from "../../_components/init-step-card";
 import { InitStartButton } from "./next-button";
 
 export const InitStart = async () => {
   const tStart = await getScopedI18n("init.step.start");
 
   return (
-    <Card w={64 * 6} maw="90vw">
+    <InitStepCard>
       <Stack>
         <Text>{tStart("description")}</Text>
 
@@ -27,6 +28,6 @@ export const InitStart = async () => {
           {tStart("action.importOldmarr")}
         </InitStartButton>
       </Stack>
-    </Card>
+    </InitStepCard>
   );
 };

apps/nextjs/src/app/[locale]/init/_steps/user/init-user.tsx

@@ -1,11 +1,10 @@
-import { Card } from "@mantine/core";
-
+import { InitStepCard } from "../../_components/init-step-card";
 import { InitUserForm } from "./init-user-form";
 
 export const InitUser = () => {
   return (
-    <Card w={64 * 6} maw="90vw">
+    <InitStepCard>
       <InitUserForm />
-    </Card>
+    </InitStepCard>
   );
 };

apps/nextjs/src/app/[locale]/init/page.tsx

@@ -9,10 +9,12 @@ import { getScopedI18n } from "@homarr/translation/server";
 import { CurrentColorSchemeCombobox } from "~/components/color-scheme/current-color-scheme-combobox";
 import { CurrentLanguageCombobox } from "~/components/language/current-language-combobox";
 import { HomarrLogoWithTitle } from "~/components/layout/logo/homarr-logo";
+import { onboardingContentWidth, onboardingMaxWidth } from "./_constants";
 import { BackToStart } from "./_steps/back";
 import { InitFinish } from "./_steps/finish/init-finish";
 import { InitGroup } from "./_steps/group/init-group";
 import { InitImport } from "./_steps/import/init-import";
+import { InitIntegrations } from "./_steps/integrations/init-integrations";
 import { InitSettings } from "./_steps/settings/init-settings";
 import { InitStart } from "./_steps/start/init-start";
 import { InitUser } from "./_steps/user/init-user";
@@ -23,6 +25,7 @@ const stepComponents: Record<OnboardingStep, null | (() => MaybePromise<JSX.Elem
   user: InitUser,
   group: InitGroup,
   settings: InitSettings,
+  integrations: InitIntegrations,
   finish: InitFinish,
 };
 
@@ -35,7 +38,7 @@ export default async function InitPage() {
   return (
     <Box mih="100dvh">
       <Center>
-        <Stack align="center" mt="xl">
+        <Stack align="center" mt="xl" w={onboardingContentWidth} maw={onboardingMaxWidth}>
           <HomarrLogoWithTitle size="lg" />
           <Stack gap={6} align="center">
             <Title order={3} fw={400} ta="center">

apps/nextjs/src/app/[locale]/layout.tsx

@@ -1,6 +1,7 @@
 import type { Metadata, Viewport } from "next";
 import { Inter } from "next/font/google";
 
+import "@gfazioli/mantine-onboarding-tour/styles.css";
 import "@homarr/notifications/styles.css";
 import "@homarr/spotlight/styles.css";
 import "@homarr/ui/styles.css";

apps/nextjs/src/app/[locale]/manage/apps/page.tsx

@@ -11,6 +11,7 @@ import type { inferSearchParamsFromSchema } from "@homarr/common/types";
 import { getI18n, getScopedI18n } from "@homarr/translation/server";
 import { Link, SearchInput, TablePagination } from "@homarr/ui";
 
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
 import { MobileAffixButton } from "~/components/manage/mobile-affix-button";
 import { NoResults } from "~/components/no-results";
@@ -45,9 +46,11 @@ export default async function AppsPage(props: AppsPageProps) {
       title={t("page.list.title")}
       primaryAction={
         canCreate ? (
-          <MobileAffixButton component={Link} href="/manage/apps/new">
-            {t("page.create.title")}
-          </MobileAffixButton>
+          <TourTarget id="manage-apps-create">
+            <MobileAffixButton component={Link} href="/manage/apps/new">
+              {t("page.create.title")}
+            </MobileAffixButton>
+          </TourTarget>
         ) : undefined
       }
       toolbar={<SearchInput placeholder={`${t("search")}...`} defaultValue={searchParams.search} flexExpand />}
@@ -56,11 +59,13 @@ export default async function AppsPage(props: AppsPageProps) {
     >
       {apps.length === 0 && <AppNoResults />}
       {apps.length > 0 && (
-        <Stack gap="sm">
-          {apps.map((app) => (
-            <AppCard key={app.id} app={app} />
-          ))}
-        </Stack>
+        <TourTarget id="manage-apps-list">
+          <Stack gap="sm">
+            {apps.map((app) => (
+              <AppCard key={app.id} app={app} />
+            ))}
+          </Stack>
+        </TourTarget>
       )}
     </ManagePageLayout>
   );

apps/nextjs/src/app/[locale]/manage/boards/page.tsx

@@ -28,6 +28,7 @@ import { getScopedI18n } from "@homarr/translation/server";
 import { Link, UserAvatar } from "@homarr/ui";
 
 import { getBoardPermissionsAsync } from "~/components/board/permissions/server";
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
 import { NoResults } from "~/components/no-results";
 import { BoardCardMenuDropdown } from "./_components/board-card-menu-dropdown";
@@ -42,18 +43,26 @@ export default async function ManageBoardsPage() {
   return (
     <ManagePageLayout
       title={t("title")}
-      primaryAction={canCreateBoards ? <CreateBoardButton /> : undefined}
+      primaryAction={
+        canCreateBoards ? (
+          <TourTarget id="manage-boards-create">
+            <CreateBoardButton />
+          </TourTarget>
+        ) : undefined
+      }
       floatingPrimaryAction={canCreateBoards}
     >
       {boards.length === 0 && <NoResults icon={IconLayoutDashboard} title={t("noResults.title")} />}
       {boards.length > 0 && (
-        <Grid>
-          {boards.map((board) => (
-            <GridCol span={{ base: 12, md: 6 }} key={board.id}>
-              <BoardCard board={board} />
-            </GridCol>
-          ))}
-        </Grid>
+        <TourTarget id="manage-boards-list">
+          <Grid>
+            {boards.map((board) => (
+              <GridCol span={{ base: 12, md: 6 }} key={board.id}>
+                <BoardCard board={board} />
+              </GridCol>
+            ))}
+          </Grid>
+        </TourTarget>
       )}
     </ManagePageLayout>
   );

apps/nextjs/src/app/[locale]/manage/integrations/new/_integration-new-dropdown.tsx

@@ -1,59 +0,0 @@
-"use client";
-
-import type { ChangeEvent } from "react";
-import React, { useMemo, useState } from "react";
-import { Flex, Group, Menu, ScrollArea, Text, TextInput } from "@mantine/core";
-import { IconSearch } from "@tabler/icons-react";
-
-import { getIntegrationName, integrationKinds } from "@homarr/definitions";
-import { useI18n } from "@homarr/translation/client";
-import { IntegrationAvatar, Link } from "@homarr/ui";
-
-interface IntegrationCreateDropdownContentProps {
-  enableMockIntegration: boolean;
-}
-
-export const IntegrationCreateDropdownContent = ({ enableMockIntegration }: IntegrationCreateDropdownContentProps) => {
-  const t = useI18n();
-  const [search, setSearch] = useState("");
-
-  const filteredKinds = useMemo(() => {
-    return integrationKinds
-      .filter((kind) => enableMockIntegration || kind !== "mock")
-      .filter((kind) => getIntegrationName(kind).toLowerCase().includes(search.toLowerCase().trim()))
-      .sort((kindA, kindB) => getIntegrationName(kindA).localeCompare(getIntegrationName(kindB)));
-  }, [search, enableMockIntegration]);
-
-  const handleSearch = React.useCallback(
-    (event: ChangeEvent<HTMLInputElement>) => setSearch(event.target.value),
-    [setSearch],
-  );
-
-  return (
-    <Flex direction={{ base: "column-reverse", md: "column" }} gap="sm">
-      <TextInput
-        leftSection={<IconSearch stroke={1.5} size={20} />}
-        placeholder={t("integration.page.list.search")}
-        value={search}
-        data-autofocus
-        onChange={handleSearch}
-        variant="filled"
-      />
-
-      {filteredKinds.length > 0 ? (
-        <ScrollArea.Autosize mah={384}>
-          {filteredKinds.map((kind) => (
-            <Menu.Item component={Link} href={`/manage/integrations/new?kind=${kind}`} key={kind}>
-              <Group>
-                <IntegrationAvatar kind={kind} size="sm" />
-                <Text size="sm">{getIntegrationName(kind)}</Text>
-              </Group>
-            </Menu.Item>
-          ))}
-        </ScrollArea.Autosize>
-      ) : (
-        <Menu.Item disabled>{t("common.noResults")}</Menu.Item>
-      )}
-    </Flex>
-  );
-};

apps/nextjs/src/app/[locale]/manage/integrations/new/_integration-new-form-wrapper.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+
+import type { IntegrationKind } from "@homarr/definitions";
+
+import { NewIntegrationForm } from "./_integration-new-form";
+
+interface IntegrationNewFormWrapperProps {
+  kind: IntegrationKind;
+  initialUrl?: string;
+  initialName?: string;
+}
+
+export const IntegrationNewFormWrapper = ({ kind, initialUrl, initialName }: IntegrationNewFormWrapperProps) => {
+  const router = useRouter();
+
+  return (
+    <NewIntegrationForm
+      kind={kind}
+      initialUrl={initialUrl}
+      initialName={initialName}
+      onSuccess={() => router.push("/manage/integrations")}
+    />
+  );
+};

apps/nextjs/src/app/[locale]/manage/integrations/new/_integration-new-form.tsx

@@ -1,9 +1,9 @@
 "use client";
 
 import { startTransition, useState } from "react";
-import { useRouter } from "next/navigation";
 import {
   Alert,
+  Anchor,
   Button,
   Checkbox,
   Collapse,
@@ -16,7 +16,7 @@ import {
   Text,
   TextInput,
 } from "@mantine/core";
-import { IconCheck, IconInfoCircle } from "@tabler/icons-react";
+import { IconCheck, IconExternalLink, IconInfoCircle, IconKey } from "@tabler/icons-react";
 import { z } from "zod/v4";
 
 import { clientApi } from "@homarr/api/client";
@@ -27,6 +27,7 @@ import type { IntegrationKind } from "@homarr/definitions";
 import {
   getAllSecretKindOptions,
   getIconUrl,
+  getIntegrationApiKeyUrl,
   getIntegrationDefaultUrl,
   getIntegrationName,
   integrationDefs,
@@ -45,9 +46,13 @@ import { IntegrationTestConnectionError } from "../_components/test-connection/i
 import type { AnyMappedTestConnectionError } from "../_components/test-connection/types";
 
 interface NewIntegrationFormProps {
-  searchParams: Partial<z.infer<typeof integrationCreateSchema>> & {
-    kind: IntegrationKind;
-  };
+  kind: IntegrationKind;
+  initialUrl?: string;
+  initialName?: string;
+  onSuccess: () => void;
+  onCancel?: () => void;
+  onSkip?: () => void;
+  isOnboarding?: boolean;
 }
 
 const formSchema = integrationCreateSchema.omit({ kind: true, app: true }).and(
@@ -58,39 +63,48 @@ const formSchema = integrationCreateSchema.omit({ kind: true, app: true }).and(
   }),
 );
 
-export const NewIntegrationForm = ({ searchParams }: NewIntegrationFormProps) => {
+export const NewIntegrationForm = ({
+  kind,
+  initialUrl,
+  initialName,
+  onSuccess,
+  onCancel,
+  onSkip,
+  isOnboarding = false,
+}: NewIntegrationFormProps) => {
   const t = useI18n();
-  const secretKinds = getAllSecretKindOptions(searchParams.kind);
+  const secretKinds = getAllSecretKindOptions(kind);
   const hasUrlSecret = secretKinds.some((kinds) => kinds.includes("url"));
-  const router = useRouter();
   const { data: session } = useSession();
-  const canCreateApps = session?.user.permissions.includes("app-create") ?? false;
+  const canCreateApps = !isOnboarding && (session?.user.permissions.includes("app-create") ?? false);
 
-  let url = searchParams.url ?? getIntegrationDefaultUrl(searchParams.kind) ?? "";
+  let url = initialUrl ?? getIntegrationDefaultUrl(kind) ?? "";
   if (hasUrlSecret) {
-    // Placeholder Url, replaced with origin of the secret Url on submit
     url = "http://localhost";
   }
   const form = useZodForm(formSchema, {
     initialValues: {
-      name: searchParams.name ?? getIntegrationName(searchParams.kind),
+      name: initialName ?? getIntegrationName(kind),
       url,
       secrets: secretKinds[0].map((kind) => ({
         kind,
         value: "",
       })),
-      attemptSearchEngineCreation: true,
-      hasApp: false,
-      appHref: url,
+      attemptSearchEngineCreation: !isOnboarding,
+      hasApp: !isOnboarding,
+      appHref: isOnboarding ? null : url,
       appId: null,
     },
   });
 
-  const { mutateAsync: createIntegrationAsync, isPending } = clientApi.integration.create.useMutation({
+  const { mutateAsync: createIntegrationAsync, isPending: isCreatePending } = clientApi.integration.create.useMutation({
     async onSuccess() {
       await revalidatePathActionAsync("/manage/integrations");
     },
   });
+  const { mutateAsync: createOnboardingIntegrationAsync, isPending: isOnboardingCreatePending } =
+    clientApi.onboard.createIntegration.useMutation();
+  const isPending = isCreatePending || isOnboardingCreatePending;
   const [error, setError] = useState<null | AnyMappedTestConnectionError>(null);
 
   const handleSubmitAsync = async ({ appId, appHref, hasApp, ...values }: FormType) => {
@@ -98,6 +112,39 @@ export const NewIntegrationForm = ({ searchParams }: NewIntegrationFormProps) =>
       ? new URL(values.secrets.find((secret) => secret.kind === "url")?.value ?? values.url).origin
       : values.url;
 
+    const onMutationSuccess = (data: { error?: AnyMappedTestConnectionError } | undefined | void) => {
+      if (data && "error" in data && data.error) {
+        setError(data.error);
+        showErrorNotification({
+          title: t("integration.page.create.notification.error.title"),
+          message: t("integration.page.create.notification.error.message"),
+        });
+        return;
+      }
+
+      showSuccessNotification({
+        title: t("integration.page.create.notification.success.title"),
+        message: t("integration.page.create.notification.success.message"),
+      });
+
+      onSuccess();
+    };
+
+    const onMutationError = () => {
+      showErrorNotification({
+        title: t("integration.page.create.notification.error.title"),
+        message: t("integration.page.create.notification.error.message"),
+      });
+    };
+
+    if (isOnboarding) {
+      await createOnboardingIntegrationAsync(
+        { kind, name: values.name, url, secrets: values.secrets },
+        { onSuccess: onMutationSuccess, onError: onMutationError },
+      );
+      return;
+    }
+
     const hasCustomHref = appHref !== null && appHref.trim().length >= 1;
 
     const app = hasApp
@@ -106,49 +153,21 @@ export const NewIntegrationForm = ({ searchParams }: NewIntegrationFormProps) =>
         : {
             name: values.name,
             href: hasCustomHref ? appHref : url,
-            iconUrl: getIconUrl(searchParams.kind),
+            iconUrl: getIconUrl(kind),
             description: null,
             pingUrl: url,
           }
       : undefined;
 
     await createIntegrationAsync(
-      {
-        kind: searchParams.kind,
-        ...values,
-        url,
-        app,
-      },
-      {
-        onSuccess(data) {
-          // We do it this way as we are unable to send a typesafe error through onError
-          if (data?.error) {
-            setError(data.error);
-            showErrorNotification({
-              title: t("integration.page.create.notification.error.title"),
-              message: t("integration.page.create.notification.error.message"),
-            });
-            return;
-          }
-
-          showSuccessNotification({
-            title: t("integration.page.create.notification.success.title"),
-            message: t("integration.page.create.notification.success.message"),
-          });
-
-          router.push("/manage/integrations");
-        },
-        onError: () => {
-          showErrorNotification({
-            title: t("integration.page.create.notification.error.title"),
-            message: t("integration.page.create.notification.error.message"),
-          });
-        },
-      },
+      { kind, ...values, url, app },
+      { onSuccess: onMutationSuccess, onError: onMutationError },
     );
   };
 
-  const supportsSearchEngine = integrationDefs[searchParams.kind].category.flat().includes("search");
+  const integrationCategories = integrationDefs[kind].category.flat();
+  const supportsSearchEngine =
+    integrationCategories.includes("search") && !integrationCategories.includes("mediaSearch");
 
   return (
     <form onSubmit={form.onSubmit((value) => void handleSubmitAsync(value))}>
@@ -175,27 +194,39 @@ export const NewIntegrationForm = ({ searchParams }: NewIntegrationFormProps) =>
                 <Text c={"blue"}>{t("integration.secrets.noSecretsRequired.text")}</Text>
               </Alert>
             )}
+            <ApiKeySettingsLink kind={kind} url={form.values.url} />
           </Stack>
         </Fieldset>
 
         {error !== null && <IntegrationTestConnectionError error={error} url={form.values.url} />}
 
-        {supportsSearchEngine && (
+        {!isOnboarding && supportsSearchEngine && (
           <Checkbox
             label={t("integration.field.attemptSearchEngineCreation.label")}
             description={t("integration.field.attemptSearchEngineCreation.description", {
-              kind: getIntegrationName(searchParams.kind),
+              kind: getIntegrationName(kind),
             })}
             {...form.getInputProps("attemptSearchEngineCreation", { type: "checkbox" })}
           />
         )}
 
-        <AppForm form={form} canCreateApps={canCreateApps} />
+        {!isOnboarding && <AppForm form={form} canCreateApps={canCreateApps} />}
 
         <Group justify="end" align="center">
-          <Button variant="default" component={Link} href="/manage/integrations">
-            {t("common.action.backToOverview")}
-          </Button>
+          {onCancel ? (
+            <Button variant="default" onClick={onCancel}>
+              {t("common.action.backToOverview")}
+            </Button>
+          ) : (
+            <Button variant="default" component={Link} href="/manage/integrations">
+              {t("common.action.backToOverview")}
+            </Button>
+          )}
+          {onSkip && (
+            <Button variant="default" onClick={onSkip}>
+              {t("common.action.skip")}
+            </Button>
+          )}
           <Button type="submit" loading={isPending}>
             {t("integration.testConnection.action.create")}
           </Button>
@@ -266,6 +297,40 @@ const AppForm = ({ form, canCreateApps }: { form: UseFormReturnType<FormType>; c
   );
 };
 
+const normalizeUrl = (raw: string): string | null => {
+  try {
+    return new URL(raw).href;
+  } catch {
+    // Bare IP / hostname — prepend http:// and retry
+  }
+  try {
+    return new URL(`http://${raw}`).href;
+  } catch {
+    return null;
+  }
+};
+
+const ApiKeySettingsLink = ({ kind, url }: { kind: IntegrationKind; url: string }) => {
+  const t = useI18n();
+  const apiKeyUrl = getIntegrationApiKeyUrl(url, kind);
+  if (!apiKeyUrl) return null;
+
+  const resolved = normalizeUrl(url);
+  if (!resolved) return null;
+
+  const fullApiKeyUrl = getIntegrationApiKeyUrl(resolved, kind);
+
+  return (
+    <Anchor href={fullApiKeyUrl ?? apiKeyUrl} target="_blank" rel="noopener noreferrer" size="sm">
+      <Group gap={4}>
+        <IconKey size={14} stroke={1.5} />
+        <Text size="sm">{t("integration.field.apiKeySettings.label")}</Text>
+        <IconExternalLink size={14} stroke={1.5} />
+      </Group>
+    </Anchor>
+  );
+};
+
 type IntegrationAppSelectProps = Modify<
   GetInputPropsReturnType,
   {

apps/nextjs/src/app/[locale]/manage/integrations/new/_integration-new-select-grid.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+
+import type { IntegrationKind } from "@homarr/definitions";
+
+import { IntegrationSelectGrid } from "~/components/integration/integration-select-grid";
+
+interface IntegrationNewSelectGridProps {
+  enableMockIntegration: boolean;
+}
+
+export const IntegrationNewSelectGrid = ({ enableMockIntegration }: IntegrationNewSelectGridProps) => {
+  const router = useRouter();
+
+  const handleSelect = (kind: IntegrationKind) => {
+    router.push(`/manage/integrations/new?kind=${kind}`);
+  };
+
+  return <IntegrationSelectGrid onSelect={handleSelect} enableMockIntegration={enableMockIntegration} />;
+};

apps/nextjs/src/app/[locale]/manage/integrations/new/page.tsx

@@ -3,21 +3,21 @@ import { Container, Group, Stack, Title } from "@mantine/core";
 import { z } from "zod/v4";
 
 import { auth } from "@homarr/auth/next";
-import type { IntegrationKind } from "@homarr/definitions";
 import { getIntegrationName, integrationKinds } from "@homarr/definitions";
 import { getScopedI18n } from "@homarr/translation/server";
 import { IntegrationAvatar } from "@homarr/ui";
-import type { integrationCreateSchema } from "@homarr/validation/integration";
 
 import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
-import { NewIntegrationForm } from "./_integration-new-form";
+import { env } from "~/env";
+import { IntegrationNewFormWrapper } from "./_integration-new-form-wrapper";
+import { IntegrationNewSelectGrid } from "./_integration-new-select-grid";
 
 interface NewIntegrationPageProps {
-  searchParams: Promise<
-    Partial<z.infer<typeof integrationCreateSchema>> & {
-      kind: IntegrationKind;
-    }
-  >;
+  searchParams: Promise<{
+    kind?: string;
+    url?: string;
+    name?: string;
+  }>;
 }
 
 export default async function IntegrationsNewPage(props: NewIntegrationPageProps) {
@@ -28,8 +28,20 @@ export default async function IntegrationsNewPage(props: NewIntegrationPageProps
   }
 
   const result = z.enum(integrationKinds).safeParse(searchParams.kind);
+
   if (!result.success) {
-    notFound();
+    const t = await getScopedI18n("integration");
+    return (
+      <>
+        <DynamicBreadcrumb />
+        <Container>
+          <Stack>
+            <Title>{t("action.create")}</Title>
+            <IntegrationNewSelectGrid enableMockIntegration={env.UNSAFE_ENABLE_MOCK_INTEGRATION} />
+          </Stack>
+        </Container>
+      </>
+    );
   }
 
   const tCreate = await getScopedI18n("integration.page.create");
@@ -45,7 +57,7 @@ export default async function IntegrationsNewPage(props: NewIntegrationPageProps
             <IntegrationAvatar kind={currentKind} size="md" />
             <Title>{tCreate("title", { name: getIntegrationName(currentKind) })}</Title>
           </Group>
-          <NewIntegrationForm searchParams={searchParams} />
+          <IntegrationNewFormWrapper kind={currentKind} initialUrl={searchParams.url} initialName={searchParams.name} />
         </Stack>
       </Container>
     </>

apps/nextjs/src/app/[locale]/manage/integrations/page.tsx

@@ -1,5 +1,4 @@
 import { Fragment } from "react";
-import type { PropsWithChildren } from "react";
 import { redirect } from "next/navigation";
 import {
   AccordionControl,
@@ -8,12 +7,8 @@ import {
   ActionIcon,
   ActionIconGroup,
   Anchor,
-  Button,
   Divider,
   Group,
-  Menu,
-  MenuDropdown,
-  MenuTarget,
   Stack,
   Table,
   TableTbody,
@@ -23,7 +18,7 @@ import {
   TableTr,
   Text,
 } from "@mantine/core";
-import { IconChevronDown, IconPencil, IconPlugX } from "@tabler/icons-react";
+import { IconPencil, IconPlugX } from "@tabler/icons-react";
 
 import type { RouterOutputs } from "@homarr/api";
 import { api } from "@homarr/api/server";
@@ -34,13 +29,12 @@ import { getIntegrationName } from "@homarr/definitions";
 import { getScopedI18n } from "@homarr/translation/server";
 import { CountBadge, IntegrationAvatar, Link } from "@homarr/ui";
 
-import { ManageMobilePrimaryAction } from "~/components/manage/manage-mobile-primary-action";
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
+import { MobileAffixButton } from "~/components/manage/mobile-affix-button";
 import { NoResults } from "~/components/no-results";
-import { env } from "~/env";
 import { ActiveTabAccordion } from "../../../../components/active-tab-accordion";
 import { DeleteIntegrationActionButton } from "./_integration-buttons";
-import { IntegrationCreateDropdownContent } from "./new/_integration-new-dropdown";
 import classes from "./page.module.css";
 
 interface IntegrationsPageProps {
@@ -67,41 +61,22 @@ export default async function IntegrationsPage(props: IntegrationsPageProps) {
       title={t("page.list.title")}
       primaryAction={
         canCreateIntegrations ? (
-          <ManageMobilePrimaryAction>
-            <IntegrationSelectMenu>
-              <MenuTarget>
-                <Button rightSection={<IconChevronDown size={16} stroke={1.5} />}>{t("action.create")}</Button>
-              </MenuTarget>
-            </IntegrationSelectMenu>
-          </ManageMobilePrimaryAction>
+          <TourTarget id="manage-integrations-create">
+            <MobileAffixButton component={Link} href="/manage/integrations/new">
+              {t("action.create")}
+            </MobileAffixButton>
+          </TourTarget>
         ) : undefined
       }
       floatingPrimaryAction={canCreateIntegrations}
     >
-      <IntegrationList integrations={integrations} activeTab={searchParams.tab} />
+      <TourTarget id="manage-integrations-list">
+        <IntegrationList integrations={integrations} activeTab={searchParams.tab} />
+      </TourTarget>
     </ManagePageLayout>
   );
 }
 
-const IntegrationSelectMenu = ({ children }: PropsWithChildren) => {
-  return (
-    <Menu
-      width={256}
-      trapFocus
-      position="bottom-end"
-      withinPortal
-      shadow="md"
-      keepMounted={false}
-      withInitialFocusPlaceholder={false}
-    >
-      {children}
-      <MenuDropdown>
-        <IntegrationCreateDropdownContent enableMockIntegration={env.UNSAFE_ENABLE_MOCK_INTEGRATION} />
-      </MenuDropdown>
-    </Menu>
-  );
-};
-
 interface IntegrationListProps {
   integrations: RouterOutputs["integration"]["all"];
   activeTab?: IntegrationKind;
@@ -134,12 +109,12 @@ const IntegrationList = async ({ integrations, activeTab }: IntegrationListProps
 
   return (
     <ActiveTabAccordion defaultValue={activeTab} radius="lg" classNames={classes}>
-      {entries.map(([kind, integrations], index) => (
+      {entries.map(([kind, kindIntegrations], index) => (
         <AccordionItem key={kind} value={kind} data-first={index === 0} data-last={index === entries.length - 1}>
           <AccordionControl icon={<IntegrationAvatar size="sm" kind={kind} radius="sm" />}>
             <Group>
               <Text>{getIntegrationName(kind)}</Text>
-              <CountBadge count={integrations.length} />
+              <CountBadge count={kindIntegrations.length} />
             </Group>
           </AccordionControl>
           <AccordionPanel>
@@ -152,7 +127,7 @@ const IntegrationList = async ({ integrations, activeTab }: IntegrationListProps
                 </TableTr>
               </TableThead>
               <TableTbody>
-                {integrations.map((integration) => (
+                {kindIntegrations.map((integration) => (
                   <TableTr key={integration.id}>
                     <TableTd>{integration.name}</TableTd>
                     <TableTd>
@@ -173,7 +148,7 @@ const IntegrationList = async ({ integrations, activeTab }: IntegrationListProps
                             >
                               <IconPencil size={16} stroke={1.5} />
                             </ActionIcon>
-                            <DeleteIntegrationActionButton integration={integration} count={integrations.length} />
+                            <DeleteIntegrationActionButton integration={integration} count={kindIntegrations.length} />
                           </ActionIconGroup>
                         )}
                       </Group>
@@ -184,9 +159,9 @@ const IntegrationList = async ({ integrations, activeTab }: IntegrationListProps
             </Table>
 
             <Stack gap="xs" hiddenFrom="md">
-              {integrations.map((integration, index) => (
+              {kindIntegrations.map((integration, integrationIndex) => (
                 <Fragment key={integration.id}>
-                  {index !== 0 && <Divider />}
+                  {integrationIndex !== 0 && <Divider />}
                   <Stack gap={0}>
                     <Group justify="space-between" align="center" wrap="nowrap">
                       <Text>{integration.name}</Text>
@@ -201,7 +176,7 @@ const IntegrationList = async ({ integrations, activeTab }: IntegrationListProps
                           >
                             <IconPencil size={16} stroke={1.5} />
                           </ActionIcon>
-                          <DeleteIntegrationActionButton integration={integration} count={integrations.length} />
+                          <DeleteIntegrationActionButton integration={integration} count={kindIntegrations.length} />
                         </ActionIconGroup>
                       )}
                     </Group>

apps/nextjs/src/app/[locale]/manage/layout.tsx

@@ -36,6 +36,7 @@ import { homarrLogoPath } from "~/components/layout/logo/homarr-logo";
 import type { NavigationLink } from "~/components/layout/navigation";
 import { MainNavigation } from "~/components/layout/navigation";
 import { ClientShell } from "~/components/layout/shell";
+import { ManageTourProvider } from "~/components/onboarding/manage-tour";
 
 export default async function ManageLayout({ children }: PropsWithChildren) {
   const t = await getScopedI18n("management.navbar");
@@ -45,11 +46,13 @@ export default async function ManageLayout({ children }: PropsWithChildren) {
       label: t("items.home"),
       icon: IconHomeFilled,
       href: "/manage",
+      "data-onboarding-tour-id": "manage-welcome",
     },
     {
       icon: IconLayoutDashboardFilled,
       href: "/manage/boards",
       label: t("items.boards"),
+      "data-onboarding-tour-id": "manage-boards",
     },
     {
       icon: IconBox,
@@ -59,12 +62,14 @@ export default async function ManageLayout({ children }: PropsWithChildren) {
       iconProps: {
         strokeWidth: 2.5,
       },
+      "data-onboarding-tour-id": "manage-apps",
     },
     {
       icon: IconAffiliateFilled,
       href: "/manage/integrations",
       label: t("items.integrations"),
       hidden: !session,
+      "data-onboarding-tour-id": "manage-integrations",
     },
     {
       icon: IconSearch,
@@ -74,17 +79,20 @@ export default async function ManageLayout({ children }: PropsWithChildren) {
       iconProps: {
         strokeWidth: 2.5,
       },
+      "data-onboarding-tour-id": "manage-search-engines",
     },
     {
       icon: IconPhotoFilled,
       href: "/manage/medias",
       label: t("items.medias"),
       hidden: !session,
+      "data-onboarding-tour-id": "manage-medias",
     },
     {
       icon: IconUserFilled,
       label: t("items.users.label"),
       hidden: !session?.user.permissions.includes("admin"),
+      "data-onboarding-tour-id": "manage-users",
       items: [
         {
           label: t("items.users.items.manage"),
@@ -153,6 +161,7 @@ export default async function ManageLayout({ children }: PropsWithChildren) {
       href: "/manage/settings",
       icon: IconSettingsFilled,
       hidden: !session?.user.permissions.includes("admin"),
+      "data-onboarding-tour-id": "manage-settings",
     },
     {
       label: t("items.help.label"),
@@ -191,11 +200,17 @@ export default async function ManageLayout({ children }: PropsWithChildren) {
     },
   ];
 
-  return (
+  const isAdmin = session?.user.permissions.includes("admin") ?? false;
+
+  const shell = (
     <ClientShell hasNavigation>
       <MainHeader></MainHeader>
       <MainNavigation links={navigationLinks}></MainNavigation>
       <AppShellMain>{children}</AppShellMain>
     </ClientShell>
   );
+
+  if (!session) return shell;
+
+  return <ManageTourProvider isAdmin={isAdmin}>{shell}</ManageTourProvider>;
 }

apps/nextjs/src/app/[locale]/manage/tools/docker/docker-table.tsx

@@ -1,23 +1,26 @@
 "use client";
 
+import { useRouter } from "next/navigation";
 import type { MantineColor } from "@mantine/core";
-import { Avatar, Badge, Box, Button, Group, Text } from "@mantine/core";
+import { ActionIcon, Avatar, Badge, Box, Button, Group, Menu, Text, Tooltip } from "@mantine/core";
 import {
   IconCategoryPlus,
+  IconDots,
+  IconFileText,
   IconPlayerPlay,
   IconPlayerStop,
   IconRefresh,
   IconRotateClockwise,
   IconTrash,
 } from "@tabler/icons-react";
-import type { MRT_ColumnDef } from "mantine-react-table";
+import type { MRT_ColumnDef, MRT_Row } from "mantine-react-table";
 import { MantineReactTable } from "mantine-react-table";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
-import { useTimeAgo } from "@homarr/common";
+import { humanFileSize, useTimeAgo } from "@homarr/common";
 import type { ContainerState } from "@homarr/docker";
-import { containerStateColorMap } from "@homarr/docker/shared";
+import { containerStateColorMap, cpuUsageColor, memoryUsageColor, safeValue } from "@homarr/docker/shared";
 import { useModalAction } from "@homarr/modals";
 import { AddDockerAppToHomarr } from "@homarr/modals-collection";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
@@ -27,25 +30,30 @@ import type { TablerIcon } from "@homarr/ui";
 import { OverflowBadge } from "@homarr/ui";
 import { useTranslatedMantineReactTable } from "@homarr/ui/hooks";
 
-const createColumns = (
-  t: TranslationFunction,
-): MRT_ColumnDef<RouterOutputs["docker"]["getContainers"]["containers"][number]>[] => [
+type DockerContainer = RouterOutputs["docker"]["getContainers"]["containers"][number];
+
+const createContainerLogsPath = (container: Pick<DockerContainer, "id" | "name">) =>
+  `/manage/tools/docker/logs/${container.id}?name=${encodeURIComponent(container.name)}`;
+
+const createColumns = (t: TranslationFunction): MRT_ColumnDef<DockerContainer>[] => [
   {
     accessorKey: "name",
     header: t("docker.field.name.label"),
     Cell({ renderedCellValue, row }) {
       return (
-        <Group gap="xs">
+        <Group gap="xs" wrap="nowrap">
           <Avatar
             variant="outline"
-            radius="lg"
+            radius="sm"
             size="md"
             styles={{ image: { objectFit: "contain" } }}
             src={row.original.iconUrl}
           >
             {row.original.name.at(0)?.toUpperCase()}
           </Avatar>
-          <Text>{renderedCellValue}</Text>
+          <Text truncate="end" maw={500}>
+            {renderedCellValue}
+          </Text>
         </Group>
       );
     },
@@ -76,11 +84,11 @@ const createColumns = (
     maxSize: 200,
     Cell({ renderedCellValue, cell }) {
       return (
-        <Box maw={200}>
-          <Text truncate="end" title={cell.row.original.image}>
-            {renderedCellValue}
-          </Text>
-        </Box>
+        <Tooltip label={cell.row.original.image} multiline maw={400}>
+          <Box maw={200}>
+            <Text truncate="end">{renderedCellValue}</Text>
+          </Box>
+        </Tooltip>
       );
     },
   },
@@ -95,13 +103,57 @@ const createColumns = (
       );
     },
   },
+  {
+    id: "cpuUsage",
+    accessorKey: "cpuUsage",
+    size: 120,
+    header: t("docker.field.stats.cpu.label"),
+    enableHiding: true,
+    sortingFn: (rowA, rowB) => {
+      const cpuUsageA = safeValue(rowA.original.cpuUsage);
+      const cpuUsageB = safeValue(rowB.original.cpuUsage);
+
+      return cpuUsageA - cpuUsageB;
+    },
+    Cell({ row }) {
+      const cpuUsage = safeValue(row.original.cpuUsage);
+
+      return (
+        <Text size="sm" c={cpuUsageColor(cpuUsage, row.original.state)}>
+          {cpuUsage.toFixed(2)}%
+        </Text>
+      );
+    },
+  },
+  {
+    id: "memoryUsage",
+    accessorKey: "memoryUsage",
+    size: 140,
+    header: t("docker.field.stats.memory.label"),
+    enableHiding: true,
+    sortingFn: (rowA, rowB) => {
+      const memoryUsageA = safeValue(rowA.original.memoryUsage);
+      const memoryUsageB = safeValue(rowB.original.memoryUsage);
+
+      return memoryUsageA - memoryUsageB;
+    },
+    Cell({ row }) {
+      const bytesUsage = safeValue(row.original.memoryUsage);
+
+      return (
+        <Text size="sm" c={memoryUsageColor(bytesUsage, row.original.state)}>
+          {humanFileSize(bytesUsage)}
+        </Text>
+      );
+    },
+  },
 ];
 
-export function DockerTable(initialData: RouterOutputs["docker"]["getContainers"]) {
+export function DockerTable({ containers, timestamp }: RouterOutputs["docker"]["getContainers"]) {
   const t = useI18n();
   const tDocker = useScopedI18n("docker");
   const { data } = clientApi.docker.getContainers.useQuery(undefined, {
-    initialData,
+    initialData: { containers, timestamp },
     refetchOnMount: false,
     refetchOnWindowFocus: false,
     refetchOnReconnect: false,
@@ -131,6 +183,8 @@ export function DockerTable(initialData: RouterOutputs["docker"]["getContainers"
     enableColumnFilters: false,
     enablePagination: false,
     enableRowSelection: true,
+    enableRowActions: true,
+    positionActionsColumn: "last",
     positionToolbarAlertBanner: "top",
     enableTableFooter: false,
     enableBottomToolbar: false,
@@ -141,7 +195,10 @@ export function DockerTable(initialData: RouterOutputs["docker"]["getContainers"
       autoFocus: true,
     },
 
-    initialState: { density: "xs", showGlobalFilter: true },
+    initialState: { density: "xs", showGlobalFilter: true, columnVisibility: { cpuUsage: false, memoryUsage: false } },
+    mantineTableBodyCellProps: { style: { padding: "4px 8px" } },
+    mantineTableHeadCellProps: { style: { padding: "4px 8px" } },
+    renderRowActions: ({ row }: { row: MRT_Row<DockerContainer> }) => <ContainerRowMenu container={row.original} />,
     renderTopToolbarCustomActions: () => (
       <Button variant="default" rightSection={<IconRefresh size="1rem" />} onClick={() => mutate()} loading={isPending}>
         {tDocker("action.refresh.label")}
@@ -174,28 +231,104 @@ export function DockerTable(initialData: RouterOutputs["docker"]["getContainers"
   );
 }
 
+const containerActions: { action: "start" | "stop" | "restart" | "remove"; icon: TablerIcon; color: MantineColor }[] = [
+  { action: "start", icon: IconPlayerPlay, color: "green" },
+  { action: "stop", icon: IconPlayerStop, color: "red" },
+  { action: "restart", icon: IconRotateClockwise, color: "orange" },
+  { action: "remove", icon: IconTrash, color: "red" },
+];
+
+const ContainerRowMenu = ({ container }: { container: DockerContainer }) => {
+  const t = useScopedI18n("docker.action");
+  const router = useRouter();
+  const utils = clientApi.useUtils();
+  const { openModal } = useModalAction(AddDockerAppToHomarr);
+
+  const useContainerAction = (action: "start" | "stop" | "restart" | "remove") =>
+    clientApi.docker[`${action}All`].useMutation({
+      async onSettled() {
+        await utils.docker.getContainers.invalidate();
+      },
+      onSuccess() {
+        showSuccessNotification({
+          title: t(`${action}.notification.success.title`),
+          message: t(`${action}.notification.success.message`),
+        });
+      },
+      onError() {
+        showErrorNotification({
+          title: t(`${action}.notification.error.title`),
+          message: t(`${action}.notification.error.message`),
+        });
+      },
+    });
+
+  const mutations = {
+    start: useContainerAction("start"),
+    stop: useContainerAction("stop"),
+    restart: useContainerAction("restart"),
+    remove: useContainerAction("remove"),
+  };
+
+  return (
+    <Menu withinPortal position="bottom-end" shadow="sm">
+      <Menu.Target>
+        <ActionIcon variant="subtle" color="gray" onClick={(e) => e.stopPropagation()}>
+          <IconDots size="1rem" />
+        </ActionIcon>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Item
+          leftSection={<IconFileText size="1rem" />}
+          onClick={() => router.push(createContainerLogsPath(container))}
+        >
+          {t("logs.label")}
+        </Menu.Item>
+        <Menu.Divider />
+        {containerActions.map(({ action, icon: Icon, color }) => (
+          <Menu.Item
+            key={action}
+            leftSection={<Icon size="1rem" />}
+            color={color}
+            onClick={() => mutations[action].mutate({ ids: [container.id] })}
+          >
+            {t(`${action}.label`)}
+          </Menu.Item>
+        ))}
+        <Menu.Divider />
+        <Menu.Item
+          leftSection={<IconCategoryPlus size="1rem" />}
+          color="red"
+          onClick={() => openModal({ selectedContainers: [container] })}
+        >
+          {t("addToHomarr.label")}
+        </Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+};
+
 interface ContainerActionBarProps {
-  selectedContainers: RouterOutputs["docker"]["getContainers"]["containers"];
+  selectedContainers: DockerContainer[];
 }
 
 const ContainerActionBar = ({ selectedContainers }: ContainerActionBarProps) => {
   const t = useScopedI18n("docker.action");
   const { openModal } = useModalAction(AddDockerAppToHomarr);
-  const handleClick = () => {
-    openModal({
-      selectedContainers,
-    });
-  };
 
   const selectedIds = selectedContainers.map((container) => container.id);
 
   return (
     <Group gap="xs">
-      <ContainerActionBarButton icon={IconPlayerPlay} color="green" action="start" selectedIds={selectedIds} />
-      <ContainerActionBarButton icon={IconPlayerStop} color="red" action="stop" selectedIds={selectedIds} />
-      <ContainerActionBarButton icon={IconRotateClockwise} color="orange" action="restart" selectedIds={selectedIds} />
-      <ContainerActionBarButton icon={IconTrash} color="red" action="remove" selectedIds={selectedIds} />
-      <Button leftSection={<IconCategoryPlus />} color={"red"} onClick={handleClick} variant="light">
+      {containerActions.map(({ action, icon, color }) => (
+        <ContainerActionBarButton key={action} icon={icon} color={color} action={action} selectedIds={selectedIds} />
+      ))}
+      <Button
+        leftSection={<IconCategoryPlus />}
+        color="red"
+        onClick={() => openModal({ selectedContainers })}
+        variant="light"
+      >
         {t("addToHomarr.label")}
       </Button>
     </Group>

apps/nextjs/src/app/[locale]/manage/tools/docker/logs/[containerId]/client.tsx

@@ -0,0 +1,10 @@
+"use client";
+
+import dynamic from "next/dynamic";
+
+export const ClientSideDockerLogsTerminal = dynamic(
+  () => import("./terminal").then(({ DockerLogsTerminal }) => DockerLogsTerminal),
+  {
+    ssr: false,
+  },
+);

apps/nextjs/src/app/[locale]/manage/tools/docker/logs/[containerId]/page.tsx

@@ -0,0 +1,47 @@
+import { notFound } from "next/navigation";
+import { Box, Group } from "@mantine/core";
+
+import { api } from "@homarr/api/server";
+import { auth } from "@homarr/auth/next";
+import { env } from "@homarr/docker/env";
+
+import "@xterm/xterm/css/xterm.css";
+
+import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
+import { fullHeightWithoutHeaderAndFooter } from "~/constants";
+import { ClientSideDockerLogsTerminal } from "./client";
+
+interface DockerContainerLogsPageProps {
+  params: Promise<{ containerId: string }>;
+  searchParams: Promise<{ name?: string }>;
+}
+
+export default async function DockerContainerLogsPage({ params, searchParams }: DockerContainerLogsPageProps) {
+  const session = await auth();
+  if (!(session?.user.permissions.includes("admin") && env.ENABLE_DOCKER)) {
+    notFound();
+  }
+
+  const { containerId } = await params;
+  const { name } = await searchParams;
+
+  try {
+    await api.docker.logs({ id: containerId, tail: 1 });
+  } catch {
+    notFound();
+  }
+
+  return (
+    <>
+      <Group justify="space-between" align="center" wrap="nowrap">
+        <DynamicBreadcrumb
+          dynamicMappings={new Map([[containerId, name ?? containerId]])}
+          nonInteractable={[containerId]}
+        />
+      </Group>
+      <Box style={{ borderRadius: 6 }} h={fullHeightWithoutHeaderAndFooter} p="md" bg="black">
+        <ClientSideDockerLogsTerminal containerId={containerId} />
+      </Box>
+    </>
+  );
+}

apps/nextjs/src/app/[locale]/manage/tools/docker/logs/[containerId]/terminal.module.css

@@ -0,0 +1,3 @@
+.outerTerminal > div {
+  height: 100%;
+}

apps/nextjs/src/app/[locale]/manage/tools/docker/logs/[containerId]/terminal.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+import { Box } from "@mantine/core";
+import { CanvasAddon } from "@xterm/addon-canvas";
+import { FitAddon } from "@xterm/addon-fit";
+import { Terminal } from "@xterm/xterm";
+
+import { clientApi } from "@homarr/api/client";
+
+import classes from "./terminal.module.css";
+
+interface DockerLogsTerminalProps {
+  containerId: string;
+}
+
+export const DockerLogsTerminal = ({ containerId }: DockerLogsTerminalProps) => {
+  const ref = useRef<HTMLDivElement>(null);
+  const terminalRef = useRef<Terminal | null>(null);
+  const pendingLogsRef = useRef<string[]>([]);
+  const isTerminalReadyRef = useRef(false);
+
+  const writeToTerminal = useCallback((data: string) => {
+    if (!isTerminalReadyRef.current || !terminalRef.current) {
+      pendingLogsRef.current.push(data);
+      return;
+    }
+
+    terminalRef.current.write(data);
+    terminalRef.current.refresh(0, terminalRef.current.rows - 1);
+  }, []);
+
+  clientApi.docker.subscribeLogs.useSubscription(
+    { id: containerId, tail: 200 },
+    {
+      onData: writeToTerminal,
+      onError(err) {
+        writeToTerminal(`\r\n\x1b[31m${err.message}\x1b[0m`);
+      },
+    },
+  );
+
+  useEffect(() => {
+    if (!ref.current) {
+      return () => undefined;
+    }
+
+    const canvasAddon = new CanvasAddon();
+
+    terminalRef.current = new Terminal({
+      cursorBlink: false,
+      disableStdin: true,
+      convertEol: true,
+      fontSize: 14,
+    });
+    terminalRef.current.open(ref.current);
+    terminalRef.current.loadAddon(canvasAddon);
+
+    isTerminalReadyRef.current = true;
+    const terminal = terminalRef.current;
+    pendingLogsRef.current.forEach((data) => terminal.write(data));
+    pendingLogsRef.current = [];
+    terminal.refresh(0, terminal.rows - 1);
+
+    setTimeout(() => {
+      const fitAddon = new FitAddon();
+      terminalRef.current?.loadAddon(fitAddon);
+      fitAddon.fit();
+    });
+
+    return () => {
+      isTerminalReadyRef.current = false;
+      pendingLogsRef.current = [];
+      canvasAddon.dispose();
+      terminalRef.current?.dispose();
+      terminalRef.current = null;
+    };
+  }, [writeToTerminal]);
+
+  return <Box ref={ref} className={classes.outerTerminal} h="100%" />;
+};

apps/nextjs/src/app/[locale]/manage/tools/logs/font-size-slider.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { Group, Slider, Text } from "@mantine/core";
+import { IconTextSize } from "@tabler/icons-react";
+
+import { useLogContext } from "./log-context";
+
+export const LogFontSizeSlider = () => {
+  const { fontSize, setFontSize } = useLogContext();
+
+  return (
+    <Group gap="xs" wrap="nowrap" w={160}>
+      <IconTextSize size={18} style={{ flexShrink: 0 }} />
+      <Slider
+        min={10}
+        max={24}
+        step={1}
+        value={fontSize}
+        onChange={setFontSize}
+        label={(val) => `${val}px`}
+        style={{ flex: 1 }}
+        size="xs"
+      />
+      <Text size="xs" c="dimmed" w={32} ta="right">
+        {fontSize}px
+      </Text>
+    </Group>
+  );
+};

apps/nextjs/src/app/[locale]/manage/tools/logs/log-context.tsx

@@ -6,10 +6,23 @@ import { createContext, useContext, useMemo, useState } from "react";
 import type { LogLevel } from "@homarr/core/infrastructure/logs/constants";
 import { logLevels } from "@homarr/core/infrastructure/logs/constants";
 
+const FONT_SIZE_KEY = "homarr-log-font-size";
+const DEFAULT_FONT_SIZE = 14;
+
+const readStoredFontSize = () => {
+  if (typeof window === "undefined") return DEFAULT_FONT_SIZE;
+  const stored = localStorage.getItem(FONT_SIZE_KEY);
+  if (!stored) return DEFAULT_FONT_SIZE;
+  const parsed = Number(stored);
+  return Number.isFinite(parsed) ? Math.min(Math.max(parsed, 10), 24) : DEFAULT_FONT_SIZE;
+};
+
 const LogContext = createContext<{
   level: LogLevel;
   setLevel: (level: LogLevel) => void;
   activeLevels: LogLevel[];
+  fontSize: number;
+  setFontSize: (size: number) => void;
 } | null>(null);
 
 interface LogContextProviderProps extends PropsWithChildren {
@@ -18,9 +31,19 @@ interface LogContextProviderProps extends PropsWithChildren {
 
 export const LogContextProvider = ({ defaultLevel, children }: LogContextProviderProps) => {
   const [level, setLevel] = useState(defaultLevel);
+  const [fontSize, setFontSizeRaw] = useState(readStoredFontSize);
   const activeLevels = useMemo(() => logLevels.slice(0, logLevels.indexOf(level) + 1), [level]);
 
-  return <LogContext.Provider value={{ level, setLevel, activeLevels }}>{children}</LogContext.Provider>;
+  const setFontSize = (size: number) => {
+    setFontSizeRaw(size);
+    localStorage.setItem(FONT_SIZE_KEY, String(size));
+  };
+
+  return (
+    <LogContext.Provider value={{ level, setLevel, activeLevels, fontSize, setFontSize }}>
+      {children}
+    </LogContext.Provider>
+  );
 };
 
 export const useLogContext = () => {

apps/nextjs/src/app/[locale]/manage/tools/logs/page.tsx

@@ -13,6 +13,7 @@ import { DynamicBreadcrumb } from "~/components/navigation/dynamic-breadcrumb";
 import { fullHeightWithoutHeaderAndFooter } from "~/constants";
 import { createMetaTitle } from "~/metadata";
 import { ClientSideTerminalComponent } from "./client";
+import { LogFontSizeSlider } from "./font-size-slider";
 import { LogLevelSelection } from "./level-selection";
 import { LogContextProvider } from "./log-context";
 
@@ -38,7 +39,10 @@ export default async function LogsManagementPage() {
     <LogContextProvider defaultLevel={logsEnv.LEVEL}>
       <Group justify="space-between" align="center" wrap="nowrap">
         <DynamicBreadcrumb />
-        <LogLevelSelection />
+        <Group gap="md" wrap="nowrap">
+          <LogFontSizeSlider />
+          <LogLevelSelection />
+        </Group>
       </Group>
       <Box style={{ borderRadius: 6 }} h={fullHeightWithoutHeaderAndFooter} p="md" bg="black">
         <ClientSideTerminalComponent />

apps/nextjs/src/app/[locale]/manage/tools/logs/terminal.tsx

@@ -13,9 +13,11 @@ import classes from "./terminal.module.css";
 
 export const TerminalComponent = () => {
   const ref = useRef<HTMLDivElement>(null);
-  const { activeLevels } = useLogContext();
+  const { activeLevels, fontSize } = useLogContext();
 
   const terminalRef = useRef<Terminal>(null);
+  const fitAddonRef = useRef<FitAddon>(null);
+
   clientApi.log.subscribe.useSubscription(
     {
       levels: activeLevels,
@@ -26,7 +28,6 @@ export const TerminalComponent = () => {
         terminalRef.current?.refresh(0, terminalRef.current.rows - 1);
       },
       onError(err) {
-        // This makes sense as logging might cause an infinite loop
         alert(err);
       },
     },
@@ -43,22 +44,30 @@ export const TerminalComponent = () => {
       cursorBlink: false,
       disableStdin: true,
       convertEol: true,
+      fontSize,
     });
     terminalRef.current.open(ref.current);
     terminalRef.current.loadAddon(canvasAddon);
 
-    // This is a hack to make sure the terminal is rendered before we try to fit it
-    // You can blame @Meierschlumpf for this
     setTimeout(() => {
       const fitAddon = new FitAddon();
+      fitAddonRef.current = fitAddon;
       terminalRef.current?.loadAddon(fitAddon);
       fitAddon.fit();
     });
 
     return () => {
-      terminalRef.current?.dispose();
       canvasAddon.dispose();
+      terminalRef.current?.dispose();
+      terminalRef.current = null;
     };
   }, []);
+
+  useEffect(() => {
+    if (!terminalRef.current) return;
+    terminalRef.current.options.fontSize = fontSize;
+    fitAddonRef.current?.fit();
+  }, [fontSize]);
+
   return <Box ref={ref} id="terminal" className={classes.outerTerminal} h="100%"></Box>;
 };

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_change-home-board.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import { Button, Group, Stack } from "@mantine/core";
+import type { z } from "zod/v4";
+
+import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { useZodForm } from "@homarr/form";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
+import { useI18n } from "@homarr/translation/client";
+import { userChangeHomeBoardsSchema } from "@homarr/validation/user";
+
+import type { Board } from "~/app/[locale]/boards/_types";
+import { BoardSelect } from "~/components/board/board-select";
+
+interface ChangeHomeBoardFormProps {
+  user: RouterOutputs["user"]["getById"];
+  boardsData: Pick<Board, "id" | "name" | "logoImageUrl">[];
+}
+
+export const ChangeHomeBoardForm = ({ user, boardsData }: ChangeHomeBoardFormProps) => {
+  const t = useI18n();
+  const { mutate, isPending } = clientApi.user.changeHomeBoards.useMutation({
+    async onSettled() {
+      await revalidatePathActionAsync(`/manage/users/${user.id}`);
+    },
+    onSuccess(_, variables) {
+      form.setInitialValues({
+        homeBoardId: variables.homeBoardId,
+        mobileHomeBoardId: variables.mobileHomeBoardId,
+      });
+      showSuccessNotification({
+        message: t("user.action.changeHomeBoard.notification.success.message"),
+      });
+    },
+    onError() {
+      showErrorNotification({
+        message: t("user.action.changeHomeBoard.notification.error.message"),
+      });
+    },
+  });
+  const form = useZodForm(userChangeHomeBoardsSchema, {
+    initialValues: {
+      homeBoardId: user.homeBoardId,
+      mobileHomeBoardId: user.mobileHomeBoardId,
+    },
+  });
+
+  const handleSubmit = (values: FormType) => {
+    mutate({
+      userId: user.id,
+      ...values,
+    });
+  };
+
+  return (
+    <form onSubmit={form.onSubmit(handleSubmit)}>
+      <Stack gap="md">
+        <BoardSelect
+          label={t("management.page.user.setting.general.item.board.type.general")}
+          clearable
+          boards={boardsData}
+          w="100%"
+          {...form.getInputProps("homeBoardId")}
+        />
+        <BoardSelect
+          label={t("management.page.user.setting.general.item.board.type.mobile")}
+          clearable
+          boards={boardsData}
+          w="100%"
+          {...form.getInputProps("mobileHomeBoardId")}
+        />
+
+        <Group justify="end">
+          <Button type="submit" loading={isPending}>
+            {t("common.action.save")}
+          </Button>
+        </Group>
+      </Stack>
+    </form>
+  );
+};
+
+type FormType = z.infer<typeof userChangeHomeBoardsSchema>;

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_change-search-preferences.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { Button, Group, Select, Stack, Switch } from "@mantine/core";
+import type { z } from "zod/v4";
+
+import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { useZodForm } from "@homarr/form";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
+import { useI18n } from "@homarr/translation/client";
+import { userChangeSearchPreferencesSchema } from "@homarr/validation/user";
+
+interface ChangeSearchPreferencesFormProps {
+  user: RouterOutputs["user"]["getById"];
+  searchEnginesData: { value: string; label: string }[];
+}
+
+export const ChangeSearchPreferencesForm = ({ user, searchEnginesData }: ChangeSearchPreferencesFormProps) => {
+  const t = useI18n();
+  const { mutate, isPending } = clientApi.user.changeSearchPreferences.useMutation({
+    async onSettled() {
+      await revalidatePathActionAsync(`/manage/users/${user.id}`);
+    },
+    onSuccess(_, variables) {
+      form.setInitialValues({
+        defaultSearchEngineId: variables.defaultSearchEngineId,
+        openInNewTab: variables.openInNewTab,
+        ddgBangsEnabled: variables.ddgBangsEnabled,
+      });
+      showSuccessNotification({
+        message: t("user.action.changeSearchPreferences.notification.success.message"),
+      });
+    },
+    onError() {
+      showErrorNotification({
+        message: t("user.action.changeSearchPreferences.notification.error.message"),
+      });
+    },
+  });
+  const form = useZodForm(userChangeSearchPreferencesSchema, {
+    initialValues: {
+      defaultSearchEngineId: user.defaultSearchEngineId,
+      openInNewTab: user.openSearchInNewTab,
+      ddgBangsEnabled: user.ddgBangs,
+    },
+  });
+
+  const handleSubmit = (values: FormType) => {
+    mutate({
+      userId: user.id,
+      ...values,
+    });
+  };
+
+  return (
+    <form onSubmit={form.onSubmit(handleSubmit)}>
+      <Stack gap="md">
+        <Select
+          label={t("user.field.defaultSearchEngine.label")}
+          w="100%"
+          data={searchEnginesData}
+          {...form.getInputProps("defaultSearchEngineId")}
+        />
+        <Switch
+          label={t("user.field.openSearchInNewTab.label")}
+          {...form.getInputProps("openInNewTab", { type: "checkbox" })}
+        />
+        <Switch
+          label={t("user.field.ddgBangs.label")}
+          {...form.getInputProps("ddgBangsEnabled", { type: "checkbox" })}
+        />
+
+        <Group justify="end">
+          <Button type="submit" loading={isPending}>
+            {t("common.action.save")}
+          </Button>
+        </Group>
+      </Stack>
+    </form>
+  );
+};
+
+type FormType = z.infer<typeof userChangeSearchPreferencesSchema>;

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_first-day-of-week.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import { Button, Group, Radio, Stack } from "@mantine/core";
+import type { DayOfWeek } from "@mantine/dates";
+import dayjs from "dayjs";
+import localeData from "dayjs/plugin/localeData";
+import type { z } from "zod/v4";
+
+import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { useZodForm } from "@homarr/form";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
+import { useI18n } from "@homarr/translation/client";
+import { userFirstDayOfWeekSchema } from "@homarr/validation/user";
+
+dayjs.extend(localeData);
+
+interface FirstDayOfWeekProps {
+  user: RouterOutputs["user"]["getById"];
+}
+
+const weekDays = dayjs.weekdays(false);
+
+export const FirstDayOfWeek = ({ user }: FirstDayOfWeekProps) => {
+  const t = useI18n();
+  const { mutate, isPending } = clientApi.user.changeFirstDayOfWeek.useMutation({
+    async onSettled() {
+      await revalidatePathActionAsync(`/manage/users/${user.id}`);
+    },
+    onSuccess(_, variables) {
+      form.setInitialValues({
+        firstDayOfWeek: variables.firstDayOfWeek as DayOfWeek,
+      });
+      showSuccessNotification({
+        message: t("user.action.changeFirstDayOfWeek.notification.success.message"),
+      });
+    },
+    onError() {
+      showErrorNotification({
+        message: t("user.action.changeFirstDayOfWeek.notification.error.message"),
+      });
+    },
+  });
+  const form = useZodForm(userFirstDayOfWeekSchema, {
+    initialValues: {
+      firstDayOfWeek: user.firstDayOfWeek as DayOfWeek,
+    },
+  });
+
+  const handleSubmit = (values: FormType) => {
+    mutate({
+      id: user.id,
+      ...values,
+    });
+  };
+
+  const inputProps = form.getInputProps("firstDayOfWeek");
+  const onChange = inputProps.onChange as (value: number) => void;
+  const value = (inputProps.value as number).toString();
+
+  return (
+    <form onSubmit={form.onSubmit(handleSubmit)}>
+      <Stack gap="md">
+        <Radio.Group {...inputProps} value={value} onChange={(nextValue: string) => onChange(parseInt(nextValue, 10))}>
+          <Group mt="xs">
+            <Radio value="1" label={weekDays[1]} />
+            <Radio value="6" label={weekDays[6]} />
+            <Radio value="0" label={weekDays[0]} />
+          </Group>
+        </Radio.Group>
+
+        <Group justify="end">
+          <Button type="submit" loading={isPending}>
+            {t("common.action.save")}
+          </Button>
+        </Group>
+      </Stack>
+    </form>
+  );
+};
+
+type FormType = z.infer<typeof userFirstDayOfWeekSchema>;

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_ping-icons-enabled.tsx

@@ -0,0 +1,69 @@
+"use client";
+
+import { Button, Group, Stack, Switch } from "@mantine/core";
+import type { z } from "zod/v4";
+
+import type { RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { useZodForm } from "@homarr/form";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
+import { useI18n } from "@homarr/translation/client";
+import { userPingIconsEnabledSchema } from "@homarr/validation/user";
+
+interface PingIconsEnabledProps {
+  user: RouterOutputs["user"]["getById"];
+}
+
+export const PingIconsEnabled = ({ user }: PingIconsEnabledProps) => {
+  const t = useI18n();
+  const { mutate, isPending } = clientApi.user.changePingIconsEnabled.useMutation({
+    async onSettled() {
+      await revalidatePathActionAsync(`/manage/users/${user.id}`);
+    },
+    onSuccess(_, variables) {
+      form.setInitialValues({
+        pingIconsEnabled: variables.pingIconsEnabled,
+      });
+      showSuccessNotification({
+        message: t("user.action.changePingIconsEnabled.notification.success.message"),
+      });
+    },
+    onError() {
+      showErrorNotification({
+        message: t("user.action.changePingIconsEnabled.notification.error.message"),
+      });
+    },
+  });
+  const form = useZodForm(userPingIconsEnabledSchema, {
+    initialValues: {
+      pingIconsEnabled: user.pingIconsEnabled,
+    },
+  });
+
+  const handleSubmit = (values: FormType) => {
+    mutate({
+      id: user.id,
+      ...values,
+    });
+  };
+
+  return (
+    <form onSubmit={form.onSubmit(handleSubmit)}>
+      <Stack gap="md">
+        <Switch
+          {...form.getInputProps("pingIconsEnabled", { type: "checkbox" })}
+          label={t("user.field.pingIconsEnabled.label")}
+        />
+
+        <Group justify="end">
+          <Button type="submit" loading={isPending}>
+            {t("common.action.save")}
+          </Button>
+        </Group>
+      </Stack>
+    </form>
+  );
+};
+
+type FormType = z.infer<typeof userPingIconsEnabledSchema>;

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_profile-form.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { useCallback } from "react";
+import { Button, Group, Stack, TextInput } from "@mantine/core";
+
+import type { RouterInputs, RouterOutputs } from "@homarr/api";
+import { clientApi } from "@homarr/api/client";
+import { revalidatePathActionAsync } from "@homarr/common/client";
+import { useZodForm } from "@homarr/form";
+import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
+import { useI18n } from "@homarr/translation/client";
+import { userEditProfileSchema } from "@homarr/validation/user";
+
+interface UserProfileFormProps {
+  user: RouterOutputs["user"]["getById"];
+}
+
+export const UserProfileForm = ({ user }: UserProfileFormProps) => {
+  const t = useI18n();
+  const { mutate, isPending } = clientApi.user.editProfile.useMutation({
+    async onSettled() {
+      await revalidatePathActionAsync("/manage/users");
+    },
+    onSuccess(_, variables) {
+      // Reset form initial values to reset dirty state
+      form.setInitialValues({
+        name: variables.name,
+        email: variables.email ?? "",
+      });
+      showSuccessNotification({
+        title: t("common.notification.update.success"),
+        message: t("user.action.editProfile.notification.success.message"),
+      });
+    },
+    onError(error) {
+      const message =
+        error.data?.code === "CONFLICT"
+          ? t("user.error.usernameTaken")
+          : t("user.action.editProfile.notification.error.message");
+      showErrorNotification({
+        title: t("common.notification.update.error"),
+        message,
+      });
+    },
+  });
+  const form = useZodForm(userEditProfileSchema.omit({ id: true }), {
+    initialValues: {
+      name: user.name ?? "",
+      email: user.email ?? "",
+    },
+  });
+
+  // Only credentials users can edit their profile
+  const isProviderCredentials = user.provider === "credentials";
+
+  const handleSubmit = useCallback(
+    (values: FormType) => {
+      if (!isProviderCredentials) return;
+      mutate({
+        ...values,
+        id: user.id,
+      });
+    },
+    [isProviderCredentials, mutate, user.id],
+  );
+
+  return (
+    <form onSubmit={form.onSubmit(handleSubmit)}>
+      <Stack>
+        <TextInput
+          disabled={!isProviderCredentials}
+          label={t("user.field.username.label")}
+          withAsterisk
+          {...form.getInputProps("name")}
+        />
+        <TextInput
+          disabled={!isProviderCredentials}
+          label={t("user.field.email.label")}
+          {...form.getInputProps("email")}
+        />
+
+        {isProviderCredentials && (
+          <Group justify="end">
+            <Button type="submit" disabled={!form.isDirty()} loading={isPending}>
+              {t("common.action.saveChanges")}
+            </Button>
+          </Group>
+        )}
+      </Stack>
+    </form>
+  );
+};
+
+type FormType = Omit<RouterInputs["user"]["editProfile"], "id">;

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/_components/_reset-tours.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { Badge, Button, Group, Stack, Text } from "@mantine/core";
+import { IconRefresh } from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { showSuccessNotification } from "@homarr/notifications";
+import { useScopedI18n } from "@homarr/translation/client";
+
+export const ResetTours = () => {
+  const t = useScopedI18n("management.page.user.setting.general.item.onboardingTours");
+  const utils = clientApi.useUtils();
+  const { data: tourStatus } = clientApi.user.getTourStatus.useQuery();
+  const { mutate: resetTours, isPending } = clientApi.user.resetTours.useMutation({
+    onSuccess() {
+      showSuccessNotification({
+        title: t("resetSuccess.title"),
+        message: t("resetSuccess.message"),
+      });
+      void utils.user.getTourStatus.invalidate();
+    },
+  });
+
+  const tours = [
+    { key: "management" as const, completed: tourStatus?.completedManageTour ?? false },
+    { key: "dashboard" as const, completed: tourStatus?.completedBoardTour ?? false },
+  ];
+
+  return (
+    <Stack gap="xs">
+      <Group gap="xs">
+        {tours.map(({ key, completed }) => (
+          <Badge key={key} color={completed ? "green" : "gray"} variant="light">
+            {t(`name.${key}`)}: {completed ? t("status.completed") : t("status.notStarted")}
+          </Badge>
+        ))}
+      </Group>
+      <Text size="sm" c="dimmed">
+        {t("description")}
+      </Text>
+      <Button
+        leftSection={<IconRefresh size={16} />}
+        variant="light"
+        size="sm"
+        w="fit-content"
+        onClick={() => resetTours()}
+        loading={isPending}
+      >
+        {t("reset")}
+      </Button>
+    </Stack>
+  );
+};

apps/nextjs/src/app/[locale]/manage/users/[userId]/general/page.tsx

@@ -6,13 +6,19 @@ import { api } from "@homarr/api/server";
 import { auth } from "@homarr/auth/next";
 import { getI18n, getScopedI18n } from "@homarr/translation/server";
 
+import { CurrentLanguageCombobox } from "~/components/language/current-language-combobox";
 import { DangerZoneItem, DangerZoneRoot } from "~/components/manage/danger-zone";
 import { catchTrpcNotFound } from "~/errors/trpc-catch-error";
 import { createMetaTitle } from "~/metadata";
 import { canAccessUserEditPage } from "../access";
+import { ChangeHomeBoardForm } from "./_components/_change-home-board";
+import { ChangeSearchPreferencesForm } from "./_components/_change-search-preferences";
 import { DeleteUserButton } from "./_components/_delete-user-button";
-import { UserGeneralSettingsForm } from "./_components/_general-settings-form";
+import { FirstDayOfWeek } from "./_components/_first-day-of-week";
+import { PingIconsEnabled } from "./_components/_ping-icons-enabled";
 import { UserProfileAvatarForm } from "./_components/_profile-avatar-form";
+import { UserProfileForm } from "./_components/_profile-form";
+import { ResetTours } from "./_components/_reset-tours";
 
 interface Props {
   params: Promise<{
@@ -58,7 +64,7 @@ export default async function EditUserPage(props: Props) {
 
   const boards = await api.board.getAllBoards();
   const searchEngines = await api.searchEngine.getSelectable();
-  const isSelf = session?.user.id === user.id;
+
   const isCredentialsUser = user.provider === "credentials";
 
   return (
@@ -68,25 +74,58 @@ export default async function EditUserPage(props: Props) {
           {t("management.page.user.fieldsDisabledExternalProvider")}
         </Alert>
       )}
+
       <Title>{tGeneral("title")}</Title>
-      <Group gap="xl" align="flex-start" wrap="wrap">
-        <Box flex={1} miw={{ base: "100%", md: 540 }}>
-          <UserGeneralSettingsForm
-            user={user}
-            boardsData={boards.map((board) => ({
-              id: board.id,
-              name: board.name,
-              logoImageUrl: board.logoImageUrl,
-            }))}
-            searchEnginesData={searchEngines}
-            showLanguageSelector={isSelf}
-          />
+      <Group gap="xl">
+        <Box flex={1}>
+          <UserProfileForm user={user} />
         </Box>
-        <Box w={{ base: "100%", lg: 260 }}>
+        <Box w={{ base: "100%", lg: 200 }}>
           <UserProfileAvatarForm user={user} />
         </Box>
       </Group>
 
+      {session?.user.id === user.id && (
+        <Stack mb="lg">
+          <Title order={2}>{tGeneral("item.language")}</Title>
+          <CurrentLanguageCombobox />
+        </Stack>
+      )}
+
+      <Stack mb="lg">
+        <Title order={2}>{tGeneral("item.board.title")}</Title>
+        <ChangeHomeBoardForm
+          user={user}
+          boardsData={boards.map((board) => ({
+            id: board.id,
+            name: board.name,
+            logoImageUrl: board.logoImageUrl,
+          }))}
+        />
+      </Stack>
+
+      <Stack mb="lg">
+        <Title order={2}>{tGeneral("item.search")}</Title>
+        <ChangeSearchPreferencesForm user={user} searchEnginesData={searchEngines} />
+      </Stack>
+
+      <Stack mb="lg">
+        <Title order={2}>{tGeneral("item.firstDayOfWeek")}</Title>
+        <FirstDayOfWeek user={user} />
+      </Stack>
+
+      <Stack mb="lg">
+        <Title order={2}>{tGeneral("item.accessibility")}</Title>
+        <PingIconsEnabled user={user} />
+      </Stack>
+
+      {session?.user.id === user.id && (
+        <Stack mb="lg">
+          <Title order={2}>{tGeneral("item.onboardingTours.title")}</Title>
+          <ResetTours />
+        </Stack>
+      )}
+
       <DangerZoneRoot>
         <DangerZoneItem
           label={t("user.action.delete.label")}

apps/nextjs/src/app/[locale]/manage/users/page.tsx

@@ -6,6 +6,7 @@ import { isProviderEnabled } from "@homarr/auth/server";
 import { getScopedI18n } from "@homarr/translation/server";
 import { Link } from "@homarr/ui";
 
+import { TourTarget } from "~/components/layout/header/tour-target";
 import { ManagePageLayout } from "~/components/manage/manage-page-layout";
 import { MobileAffixButton } from "~/components/manage/mobile-affix-button";
 import { createMetaTitle } from "~/metadata";
@@ -38,14 +39,18 @@ export default async function UsersPage() {
       title={t("list.title")}
       primaryAction={
         credentialsProviderEnabled ? (
-          <MobileAffixButton component={Link} href="/manage/users/create">
-            {t("create.title")}
-          </MobileAffixButton>
+          <TourTarget id="manage-users-create">
+            <MobileAffixButton component={Link} href="/manage/users/create">
+              {t("create.title")}
+            </MobileAffixButton>
+          </TourTarget>
         ) : undefined
       }
       floatingPrimaryAction={credentialsProviderEnabled}
     >
-      <UserListComponent initialUserList={userList} />
+      <TourTarget id="manage-users-list">
+        <UserListComponent initialUserList={userList} />
+      </TourTarget>
     </ManagePageLayout>
   );
 }

apps/nextjs/src/components/board/items/item-menu.tsx

@@ -85,6 +85,7 @@ const BoardItemMenuInner = ({ offset, item, resetErrorBoundary }: BoardItemMenuP
         ),
         integrationSupport: "supportedIntegrations" in currentDefinition,
         settings,
+        appId: item.kind === "app" ? (item.options.appId as string | undefined) : undefined,
       },
       {
         title(t) {

apps/nextjs/src/components/board/items/item-move-modal.tsx

@@ -1,11 +1,11 @@
 import { useCallback, useRef } from "react";
-import { Button, Grid, Group, NumberInput, Stack } from "@mantine/core";
+import { Grid, NumberInput, Stack } from "@mantine/core";
 import { z } from "zod/v4";
 
 import { useZodForm } from "@homarr/form";
 import type { GridStack } from "@homarr/gridstack";
-import { createModal } from "@homarr/modals";
-import { useI18n, useScopedI18n } from "@homarr/translation/client";
+import { createModal, ModalFormFooter, modalSizeForm } from "@homarr/modals";
+import { useI18n } from "@homarr/translation/client";
 
 import type { Item, SectionItem } from "~/app/[locale]/boards/_types";
 
@@ -16,9 +16,7 @@ interface InnerProps {
 }
 
 export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) => {
-  const tCommon = useScopedI18n("common");
   const t = useI18n();
-  // Keep track of the maximum width based on the x offset
   const maxWidthRef = useRef(innerProps.columnCount - innerProps.item.xOffset);
   const form = useZodForm(
     z.object({
@@ -38,7 +36,6 @@ export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) =
         height: innerProps.item.height,
       },
       onValuesChange(values, previous) {
-        // Update the maximum width when the x offset changes
         if (values.xOffset !== previous.xOffset) {
           maxWidthRef.current = innerProps.columnCount - values.xOffset;
         }
@@ -70,6 +67,7 @@ export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) =
           <Grid.Col span={{ base: 12, md: 6 }}>
             <NumberInput
               label={t("item.moveResize.field.xOffset.label")}
+              data-autofocus
               min={0}
               max={innerProps.columnCount - 1}
               {...form.getInputProps("xOffset")}
@@ -93,12 +91,7 @@ export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) =
             <NumberInput label={t("item.moveResize.field.height.label")} min={1} {...form.getInputProps("height")} />
           </Grid.Col>
         </Grid>
-        <Group justify="end">
-          <Button variant="subtle" onClick={actions.closeModal}>
-            {tCommon("action.cancel")}
-          </Button>
-          <Button type="submit">{tCommon("action.saveChanges")}</Button>
-        </Group>
+        <ModalFormFooter onCancel={actions.closeModal} />
       </Stack>
     </form>
   );
@@ -106,5 +99,5 @@ export const ItemMoveModal = createModal<InnerProps>(({ actions, innerProps }) =
   defaultTitle(t) {
     return t("item.moveResize.title");
   },
-  size: "lg",
+  size: modalSizeForm,
 });

apps/nextjs/src/components/board/items/item-select-modal.tsx

@@ -1,14 +1,14 @@
 import { useMemo, useState } from "react";
-import { Avatar, Button, Card, Center, Grid, Group, Input, Stack, Text, Tooltip } from "@mantine/core";
-import { IconSearch } from "@tabler/icons-react";
+import { Avatar, Box, Button, Card, Center, Group, Stack, Text, Tooltip } from "@mantine/core";
 
 import { clientApi } from "@homarr/api/client";
 import { createId, objectEntries } from "@homarr/common";
 import { getIconUrl, getIntegrationName } from "@homarr/definitions";
 import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
-import { createModal, useModalAction } from "@homarr/modals";
+import { createModal, modalSizeSelect, useModalAction } from "@homarr/modals";
 import { useSettings } from "@homarr/settings";
 import { useI18n } from "@homarr/translation/client";
+import { SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
 import type { TablerIcon } from "@homarr/ui";
 import { reduceWidgetOptionsWithDefaultValues, widgetImports } from "@homarr/widgets";
 import { WidgetEditModal } from "@homarr/widgets/modals";
@@ -86,32 +86,31 @@ export const ItemSelectModal = createModal<void>(({ actions }) => {
   };
 
   return (
-    <Stack>
-      <Input
-        value={search}
-        onChange={(event) => setSearch(event.currentTarget.value)}
-        leftSection={<IconSearch />}
-        placeholder={`${t("item.create.search")}...`}
-        data-autofocus
-        onKeyDown={(event) => {
-          // Add item if there is only one item in the list and user presses Enter
-          if (event.key === "Enter" && filteredItems.length === 1) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            handleAdd(filteredItems[0]!.kind);
-          }
-        }}
-      />
+    <SelectGridLayout
+      search={search}
+      onSearchChange={setSearch}
+      placeholder={`${t("item.create.search")}...`}
+      onSearchKeyDown={(event) => {
+        if (event.key === "Enter" && filteredItems.length === 1) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          handleAdd(filteredItems[0]!.kind);
+        }
+      }}
+    >
+      {filteredItems.map((item) => (
+        <WidgetItem key={item.kind} item={item} onSelect={() => handleAdd(item.kind)} />
+      ))}
 
-      <Grid>
-        {filteredItems.map((item) => (
-          <WidgetItem key={item.kind} item={item} onSelect={() => handleAdd(item.kind)} />
-        ))}
-      </Grid>
-    </Stack>
+      {filteredItems.length === 0 && (
+        <Center p="xl">
+          <Text c="dimmed">{t("common.noResults")}</Text>
+        </Center>
+      )}
+    </SelectGridLayout>
   );
 }).withOptions({
   defaultTitle: (t) => t("item.create.title"),
-  size: "xl",
+  size: modalSizeSelect,
 });
 
 const WidgetItem = ({
@@ -130,46 +129,58 @@ const WidgetItem = ({
   const t = useI18n();
 
   return (
-    <Grid.Col span={{ xs: 12, sm: 4, md: 3 }}>
-      <Card h="100%">
-        <Stack justify="space-between" h="100%">
-          <Stack gap="xs">
-            <Center>
-              <item.icon />
-            </Center>
-            <Text lh={1.2} style={{ whiteSpace: "normal" }} ta="center">
-              {item.name}
-            </Text>
-            <Text lh={1.2} style={{ whiteSpace: "normal" }} size="xs" ta="center" c="dimmed">
-              {item.description}
-            </Text>
-          </Stack>
-          <SupportedIntegrations mt="auto" integrations={item.supportedIntegrations} />
-          <Button onClick={onSelect} variant="light" size="xs" fullWidth>
-            {t(`item.create.addToBoard`)}
-          </Button>
-        </Stack>
-      </Card>
-    </Grid.Col>
+    <Card
+      h={selectGridCardHeight}
+      withBorder
+      pos="relative"
+      style={{ overflow: "hidden", "--_hover-opacity": "0" }}
+      onMouseEnter={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "1")}
+      onMouseLeave={(e) => e.currentTarget.style.setProperty("--_hover-opacity", "0")}
+    >
+      <Stack h="100%" gap="xs">
+        <Group gap="sm" wrap="nowrap" align="flex-start">
+          <item.icon size={22} style={{ flexShrink: 0, marginTop: 2 }} />
+          <Text lh={1.2} style={{ whiteSpace: "normal" }} fw={500} size="sm" lineClamp={2}>
+            {item.name}
+          </Text>
+        </Group>
+        <Tooltip label={item.description} multiline w={250} disabled={!item.description}>
+          <Text lh={1.2} style={{ whiteSpace: "normal" }} size="xs" c="dimmed" lineClamp={1}>
+            {item.description}
+          </Text>
+        </Tooltip>
+        <SupportedIntegrations integrations={item.supportedIntegrations} />
+      </Stack>
+      <Box
+        pos="absolute"
+        bottom={0}
+        left={0}
+        right={0}
+        p="xs"
+        style={{
+          opacity: "var(--_hover-opacity)",
+          transition: "opacity 150ms ease",
+          background: "linear-gradient(transparent, var(--mantine-color-body) 30%)",
+        }}
+      >
+        <Button onClick={onSelect} variant="light" size="xs" fullWidth>
+          {t(`item.create.addToBoard`)}
+        </Button>
+      </Box>
+    </Card>
   );
 };
 
-interface SupportedIntegrationsProps {
-  integrations: IntegrationKind[];
-  mt: string;
-}
-
-const SupportedIntegrations = ({ integrations, mt }: SupportedIntegrationsProps) => {
+const SupportedIntegrations = ({ integrations }: { integrations: IntegrationKind[] }) => {
   if (integrations.length === 0) {
     return null;
   }
 
-  // When there are 8 or more integrations, we show 6 and a "+X" avatar. Otherwise, we show all integrations.
   const countToShow = integrations.length >= 8 ? 6 : 7;
   const moreCount = integrations.length - countToShow;
 
   return (
-    <Center mt={mt}>
+    <Group gap={2} mt="auto">
       <Tooltip.Group closeDelay={100}>
         <Group gap={2}>
           {integrations.slice(0, countToShow).map((integration) => (
@@ -195,6 +206,6 @@ const SupportedIntegrations = ({ integrations, mt }: SupportedIntegrationsProps)
           )}
         </Group>
       </Tooltip.Group>
-    </Center>
+    </Group>
   );
 };

apps/nextjs/src/components/board/sections/category/category-edit-modal.tsx

@@ -1,8 +1,8 @@
-import { Button, Group, Stack, TextInput } from "@mantine/core";
+import { Stack, TextInput } from "@mantine/core";
 import { z } from "zod/v4";
 
 import { useZodForm } from "@homarr/form";
-import { createModal } from "@homarr/modals";
+import { createModal, ModalFormFooter, modalSizeForm } from "@homarr/modals";
 import { useI18n } from "@homarr/translation/client";
 
 interface Category {
@@ -36,13 +36,10 @@ export const CategoryEditModal = createModal<InnerProps>(({ actions, innerProps
     >
       <Stack>
         <TextInput label={t("section.category.field.name.label")} data-autofocus {...form.getInputProps("name")} />
-        <Group justify="right">
-          <Button onClick={actions.closeModal} variant="subtle" color="gray">
-            {t("common.action.cancel")}
-          </Button>
-          <Button type="submit">{innerProps.submitLabel}</Button>
-        </Group>
+        <ModalFormFooter onCancel={actions.closeModal} submitLabel={innerProps.submitLabel} />
       </Stack>
     </form>
   );
-}).withOptions({});
+}).withOptions({
+  size: modalSizeForm,
+});

apps/nextjs/src/components/board/sections/dynamic/dynamic-edit-modal.tsx

@@ -1,10 +1,10 @@
 "use client";
 
-import { Button, CloseButton, ColorInput, Group, Stack, TextInput, useMantineTheme } from "@mantine/core";
+import { CloseButton, ColorInput, Stack, TextInput, useMantineTheme } from "@mantine/core";
 import type { z } from "zod/v4";
 
 import { useZodForm } from "@homarr/form";
-import { createModal } from "@homarr/modals";
+import { createModal, ModalFormFooter, modalSizeForm } from "@homarr/modals";
 import { useI18n } from "@homarr/translation/client";
 import { TextMultiSelect } from "@homarr/ui";
 import { dynamicSectionOptionsSchema } from "@homarr/validation/shared";
@@ -31,7 +31,7 @@ export const DynamicSectionEditModal = createModal<ModalProps>(({ actions, inner
       })}
     >
       <Stack>
-        <TextInput label={t("section.dynamic.option.title.label")} {...form.getInputProps("title")} />
+        <TextInput label={t("section.dynamic.option.title.label")} data-autofocus {...form.getInputProps("title")} />
         <TextMultiSelect
           label={t("section.dynamic.option.customCssClasses.label")}
           {...form.getInputProps("customCssClasses")}
@@ -48,14 +48,7 @@ export const DynamicSectionEditModal = createModal<ModalProps>(({ actions, inner
           }
           {...form.getInputProps("borderColor")}
         />
-        <Group justify="end">
-          <Group justify="end" w={{ base: "100%", xs: "auto" }}>
-            <Button onClick={actions.closeModal} variant="subtle" color="gray">
-              {t("common.action.cancel")}
-            </Button>
-            <Button type="submit">{t("common.action.saveChanges")}</Button>
-          </Group>
-        </Group>
+        <ModalFormFooter onCancel={actions.closeModal} />
       </Stack>
     </form>
   );
@@ -63,5 +56,5 @@ export const DynamicSectionEditModal = createModal<ModalProps>(({ actions, inner
   defaultTitle(t) {
     return t("item.edit.title");
   },
-  size: "lg",
+  size: modalSizeForm,
 });

apps/nextjs/src/components/integration/integration-grid-shared.ts

@@ -0,0 +1,95 @@
+import { objectEntries } from "@homarr/common";
+import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
+import {
+  featuredIntegrations,
+  getIntegrationName,
+  hiddenFromOnboarding,
+  integrationDefs,
+  integrationKinds,
+} from "@homarr/definitions";
+import { widgetImports } from "@homarr/widgets";
+
+const buildWidgetsByIntegration = () => {
+  const map = Object.fromEntries(integrationKinds.map((kind) => [kind, [] as WidgetKind[]])) as Record<
+    IntegrationKind,
+    WidgetKind[]
+  >;
+
+  for (const [widgetKind, widget] of objectEntries(widgetImports)) {
+    const supported =
+      "supportedIntegrations" in widget.definition
+        ? (widget.definition.supportedIntegrations as IntegrationKind[])
+        : [];
+    for (const kind of supported) {
+      if (kind in map) {
+        map[kind].push(widgetKind);
+      }
+    }
+  }
+  return map;
+};
+
+export const widgetsByIntegration = buildWidgetsByIntegration();
+
+export const categoryTranslationKeys: Record<string, string> = {
+  dnsHole: "integration.category.dnsHole",
+  mediaService: "integration.category.mediaService",
+  calendar: "integration.category.calendar",
+  mediaSearch: "integration.category.mediaSearch",
+  mediaRelease: "integration.category.mediaRelease",
+  mediaRequest: "integration.category.mediaRequest",
+  downloadClient: "integration.category.downloadClient",
+  usenet: "integration.category.usenet",
+  torrent: "integration.category.torrent",
+  miscellaneous: "integration.category.miscellaneous",
+  smartHomeServer: "integration.category.smartHomeServer",
+  indexerManager: "integration.category.indexerManager",
+  healthMonitoring: "integration.category.healthMonitoring",
+  search: "integration.category.search",
+  mediaTranscoding: "integration.category.mediaTranscoding",
+  networkController: "integration.category.networkController",
+  releasesProvider: "integration.category.releasesProvider",
+  notifications: "integration.category.notifications",
+  firewall: "integration.category.firewall",
+  timetable: "integration.category.timetable",
+  photoService: "integration.category.photoService",
+  notes: "integration.category.notes",
+  mediaMonitoring: "integration.category.mediaMonitoring",
+  speedtest: "integration.category.speedtest",
+  analytics: "integration.category.analytics",
+};
+
+export interface IntegrationGridItem {
+  kind: IntegrationKind;
+  name: string;
+  categories: string[];
+  widgets: WidgetKind[];
+}
+
+export const buildSortedIntegrations = (
+  options: { enableMockIntegration?: boolean; onboarding?: boolean } = {},
+): IntegrationGridItem[] =>
+  integrationKinds
+    .filter((kind) => {
+      if (options.onboarding && hiddenFromOnboarding.has(kind)) return false;
+      if (options.onboarding && widgetsByIntegration[kind].length === 0) return false;
+      if (!options.enableMockIntegration && kind === "mock") return false;
+      return true;
+    })
+    .map((kind) => ({
+      kind,
+      name: getIntegrationName(kind),
+      categories: [...new Set(integrationDefs[kind].category.flat())] as string[],
+      widgets: widgetsByIntegration[kind],
+    }))
+    .sort((left, right) => {
+      const leftIdx = featuredIntegrations.indexOf(left.kind);
+      const rightIdx = featuredIntegrations.indexOf(right.kind);
+      if (leftIdx !== -1 && rightIdx !== -1) return leftIdx - rightIdx;
+      if (leftIdx !== -1) return -1;
+      if (rightIdx !== -1) return 1;
+      return right.widgets.length - left.widgets.length || left.name.localeCompare(right.name);
+    });
+
+export const filterIntegrations = (items: IntegrationGridItem[], search: string) =>
+  items.filter((i) => i.name.toLowerCase().includes(search.toLowerCase().trim()));

apps/nextjs/src/components/integration/integration-multi-select-grid.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { Badge, Card, Center, Group, Stack, Text, Tooltip } from "@mantine/core";
+import { IconBrandDocker, IconCheck, IconPuzzle } from "@tabler/icons-react";
+
+import type { IntegrationKind } from "@homarr/definitions";
+import { useI18n } from "@homarr/translation/client";
+import { IntegrationAvatar, SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
+
+import { buildSortedIntegrations, categoryTranslationKeys, filterIntegrations } from "./integration-grid-shared";
+
+interface IntegrationMultiSelectGridProps {
+  selectedKinds: IntegrationKind[];
+  onSelectionChange: (kinds: IntegrationKind[]) => void;
+  enableMockIntegration?: boolean;
+  onboarding?: boolean;
+  detectedKinds?: Set<IntegrationKind>;
+}
+
+export const IntegrationMultiSelectGrid = ({
+  selectedKinds: selectedKindsArray,
+  onSelectionChange,
+  enableMockIntegration = false,
+  onboarding = false,
+  detectedKinds,
+}: IntegrationMultiSelectGridProps) => {
+  const [search, setSearch] = useState("");
+  const selectedKinds = useMemo(() => new Set(selectedKindsArray), [selectedKindsArray]);
+  const t = useI18n();
+
+  const toggleKind = useCallback(
+    (kind: IntegrationKind) => {
+      const current = new Set(selectedKindsArray);
+      if (current.has(kind)) {
+        current.delete(kind);
+      } else {
+        current.add(kind);
+      }
+      onSelectionChange(Array.from(current));
+    },
+    [selectedKindsArray, onSelectionChange],
+  );
+
+  const integrations = useMemo(
+    () => buildSortedIntegrations({ enableMockIntegration, onboarding }),
+    [enableMockIntegration, onboarding],
+  );
+
+  const sorted = useMemo(() => {
+    if (!detectedKinds || detectedKinds.size === 0) return integrations;
+    const detected = integrations.filter((i) => detectedKinds.has(i.kind));
+    const rest = integrations.filter((i) => !detectedKinds.has(i.kind));
+    return [...detected, ...rest];
+  }, [integrations, detectedKinds]);
+
+  const filtered = useMemo(() => filterIntegrations(sorted, search), [sorted, search]);
+
+  return (
+    <SelectGridLayout
+      search={search}
+      onSearchChange={setSearch}
+      placeholder={`${t("integration.page.list.search")}...`}
+      disableScroll={onboarding}
+      disableAutoFocus={onboarding}
+    >
+      {filtered.map((integration) => {
+        const isSelected = selectedKinds.has(integration.kind);
+        const isDetected = detectedKinds?.has(integration.kind) ?? false;
+        return (
+          <Card
+            key={integration.kind}
+            h={selectGridCardHeight}
+            style={{
+              cursor: "pointer",
+              borderColor: isSelected ? "var(--mantine-color-blue-6)" : undefined,
+              borderWidth: isSelected ? 2 : undefined,
+            }}
+            onClick={() => toggleKind(integration.kind)}
+            withBorder
+          >
+            <Stack justify="space-between" h="100%" gap="xs">
+              <Group gap="sm" wrap="nowrap" align="flex-start">
+                <IntegrationAvatar kind={integration.kind} size="sm" />
+                <Text fw={500} lh={1.2} size="sm" lineClamp={2} style={{ flex: 1 }}>
+                  {integration.name}
+                </Text>
+                {isSelected && <IconCheck size={18} color="var(--mantine-color-blue-6)" style={{ flexShrink: 0 }} />}
+              </Group>
+
+              <Stack gap={4} mt="auto">
+                {isDetected && (
+                  <Badge variant="light" color="teal" size="xs" leftSection={<IconBrandDocker size={12} />}>
+                    {t("integration.grid.detected")}
+                  </Badge>
+                )}
+                <Group gap={4} wrap="wrap">
+                  {integration.categories.slice(0, 2).map((cat) => (
+                    <Badge key={cat} variant="light" size="xs">
+                      {categoryTranslationKeys[cat] ? t(categoryTranslationKeys[cat] as never) : cat}
+                    </Badge>
+                  ))}
+                </Group>
+                {integration.widgets.length > 0 ? (
+                  <Tooltip
+                    multiline
+                    w={200}
+                    label={
+                      <Stack gap={4}>
+                        {integration.widgets.map((widgetKind) => (
+                          <Text key={widgetKind} size="xs">
+                            {t(`widget.${widgetKind}.name`)}
+                          </Text>
+                        ))}
+                      </Stack>
+                    }
+                  >
+                    <Badge variant="light" color="blue" size="sm" leftSection={<IconPuzzle size={12} />}>
+                      {t("integration.grid.widgetCount", { count: String(integration.widgets.length) })}
+                    </Badge>
+                  </Tooltip>
+                ) : (
+                  <Badge variant="light" color="gray" size="sm">
+                    {t("integration.grid.noWidgets")}
+                  </Badge>
+                )}
+              </Stack>
+            </Stack>
+          </Card>
+        );
+      })}
+
+      {filtered.length === 0 && (
+        <Center p="xl">
+          <Text c="dimmed">{t("common.noResults")}</Text>
+        </Center>
+      )}
+    </SelectGridLayout>
+  );
+};

apps/nextjs/src/components/integration/integration-select-grid.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { Badge, Card, Center, Group, Stack, Text, Tooltip } from "@mantine/core";
+import { IconPuzzle } from "@tabler/icons-react";
+
+import type { IntegrationKind } from "@homarr/definitions";
+import { useI18n } from "@homarr/translation/client";
+import { IntegrationAvatar, SelectGridLayout, selectGridCardHeight } from "@homarr/ui";
+
+import { buildSortedIntegrations, categoryTranslationKeys, filterIntegrations } from "./integration-grid-shared";
+
+interface IntegrationSelectGridProps {
+  onSelect: (kind: IntegrationKind) => void;
+  enableMockIntegration?: boolean;
+}
+
+export const IntegrationSelectGrid = ({ onSelect, enableMockIntegration = false }: IntegrationSelectGridProps) => {
+  const [search, setSearch] = useState("");
+  const t = useI18n();
+
+  const integrations = useMemo(() => buildSortedIntegrations({ enableMockIntegration }), [enableMockIntegration]);
+  const filtered = useMemo(() => filterIntegrations(integrations, search), [integrations, search]);
+
+  return (
+    <SelectGridLayout
+      search={search}
+      onSearchChange={setSearch}
+      placeholder={`${t("integration.page.list.search")}...`}
+    >
+      {filtered.map((integration) => (
+        <Card
+          key={integration.kind}
+          h={selectGridCardHeight}
+          style={{ cursor: "pointer" }}
+          onClick={() => onSelect(integration.kind)}
+          withBorder
+        >
+          <Stack justify="space-between" h="100%" gap="xs">
+            <Group gap="sm" wrap="nowrap" align="flex-start">
+              <IntegrationAvatar kind={integration.kind} size="sm" />
+              <Text fw={500} lh={1.2} size="sm" lineClamp={2}>
+                {integration.name}
+              </Text>
+            </Group>
+
+            <Stack gap={4} mt="auto">
+              <Group gap={4} wrap="wrap">
+                {integration.categories.slice(0, 2).map((cat) => (
+                  <Badge key={cat} variant="light" size="xs">
+                    {categoryTranslationKeys[cat] ? t(categoryTranslationKeys[cat] as never) : cat}
+                  </Badge>
+                ))}
+              </Group>
+              {integration.widgets.length > 0 ? (
+                <Tooltip
+                  multiline
+                  w={200}
+                  label={
+                    <Stack gap={4}>
+                      {integration.widgets.map((widgetKind) => (
+                        <Text key={widgetKind} size="xs">
+                          {t(`widget.${widgetKind}.name`)}
+                        </Text>
+                      ))}
+                    </Stack>
+                  }
+                >
+                  <Badge variant="light" color="blue" size="sm" leftSection={<IconPuzzle size={12} />}>
+                    {t("integration.grid.widgetCount", { count: String(integration.widgets.length) })}
+                  </Badge>
+                </Tooltip>
+              ) : (
+                <Badge variant="light" color="gray" size="sm">
+                  {t("integration.grid.noWidgets")}
+                </Badge>
+              )}
+            </Stack>
+          </Stack>
+        </Card>
+      ))}
+
+      {filtered.length === 0 && (
+        <Center p="xl">
+          <Text c="dimmed">{t("common.noResults")}</Text>
+        </Center>
+      )}
+    </SelectGridLayout>
+  );
+};

apps/nextjs/src/components/integration/integration-select-modal.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useState } from "react";
+import { Group, ScrollArea, Title } from "@mantine/core";
+import { IconArrowLeft } from "@tabler/icons-react";
+
+import type { IntegrationKind } from "@homarr/definitions";
+import { getIntegrationName } from "@homarr/definitions";
+import { createModal, modalSizeSelect } from "@homarr/modals";
+import { IntegrationAvatar } from "@homarr/ui";
+
+import { NewIntegrationForm } from "~/app/[locale]/manage/integrations/new/_integration-new-form";
+import { IntegrationSelectGrid } from "./integration-select-grid";
+
+interface IntegrationSelectModalProps {
+  onSuccess?: () => void;
+  enableMockIntegration?: boolean;
+}
+
+export const IntegrationSelectModal = createModal<IntegrationSelectModalProps>(({ actions, innerProps }) => {
+  const [step, setStep] = useState<"select" | "form">("select");
+  const [selectedKind, setSelectedKind] = useState<IntegrationKind | null>(null);
+
+  const handleSelect = (kind: IntegrationKind) => {
+    setSelectedKind(kind);
+    setStep("form");
+  };
+
+  const handleBack = () => {
+    setStep("select");
+    setSelectedKind(null);
+  };
+
+  const handleSuccess = () => {
+    innerProps.onSuccess?.();
+    actions.closeModal();
+  };
+
+  if (step === "form" && selectedKind) {
+    return (
+      <ScrollArea.Autosize mah="80vh">
+        <Group gap="xs" mb="md" style={{ cursor: "pointer" }} onClick={handleBack}>
+          <IconArrowLeft size={18} />
+          <IntegrationAvatar kind={selectedKind} size="sm" />
+          <Title order={4}>{getIntegrationName(selectedKind)}</Title>
+        </Group>
+        <NewIntegrationForm kind={selectedKind} onSuccess={handleSuccess} onCancel={handleBack} />
+      </ScrollArea.Autosize>
+    );
+  }
+
+  return <IntegrationSelectGrid onSelect={handleSelect} enableMockIntegration={innerProps.enableMockIntegration} />;
+}).withOptions({
+  defaultTitle: (t) => t("integration.action.create"),
+  size: modalSizeSelect,
+});

apps/nextjs/src/components/layout/header.tsx

@@ -6,6 +6,7 @@ import { Link } from "@homarr/ui";
 
 import { ClientBurger } from "./header/burger";
 import { DesktopSearchInput, MobileSearchButton } from "./header/search";
+import { TourTarget } from "./header/tour-target";
 import { UserButton } from "./header/user";
 import { HomarrLogoWithTitle } from "./logo/homarr-logo";
 
@@ -25,11 +26,15 @@ export const MainHeader = ({ logo, actions, hasNavigation = true }: Props) => {
             {logo ?? <HomarrLogoWithTitle size="md" />}
           </UnstyledButton>
         </Group>
-        <DesktopSearchInput />
+        <TourTarget id="board-search">
+          <DesktopSearchInput />
+        </TourTarget>
         <Group h="100%" align="center" justify="end" style={{ flex: 1 }} wrap="nowrap">
           {actions}
           <MobileSearchButton />
-          <UserButton />
+          <TourTarget id="board-user-menu">
+            <UserButton />
+          </TourTarget>
         </Group>
       </Group>
       <Spotlight />

apps/nextjs/src/components/layout/header/tour-target.tsx

@@ -0,0 +1,11 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
+import { Box } from "@mantine/core";
+
+export const TourTarget = ({ id, children }: { id: string; children: ReactNode }) => (
+  <OnboardingTour.Target id={id}>
+    <Box data-tour-target={id}>{children}</Box>
+  </OnboardingTour.Target>
+);

apps/nextjs/src/components/layout/navigation-link.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from "react";
 import { usePathname } from "next/navigation";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
 import { NavLink } from "@mantine/core";
 
 import { Link } from "@homarr/ui";
@@ -9,9 +10,15 @@ import { Link } from "@homarr/ui";
 export const CommonNavLink = (props: ClientNavigationLink) =>
   "href" in props ? <NavLinkHref {...props} /> : <NavLinkWithItems {...props} />;
 
+const TourTarget = ({ id, children }: { id?: string; children: ReactNode }) => {
+  if (!id) return <>{children}</>;
+  return <OnboardingTour.Target id={id}>{children}</OnboardingTour.Target>;
+};
+
 const NavLinkHref = (props: NavigationLinkHref) => {
   const pathname = usePathname();
-  return props.external ? (
+  const tourId = props["data-onboarding-tour-id"];
+  const link = props.external ? (
     <NavLink component="a" label={props.label} leftSection={props.icon} href={props.href} target="_blank" />
   ) : (
     <NavLink
@@ -19,26 +26,29 @@ const NavLinkHref = (props: NavigationLinkHref) => {
       label={props.label}
       leftSection={props.icon}
       href={props.href}
-      active={pathname === props.href}
+      active={pathname === props.href || pathname.startsWith(`${props.href}/`)}
     />
   );
+  return <TourTarget id={tourId}>{link}</TourTarget>;
 };
 
 const NavLinkWithItems = (props: NavigationLinkWithItems) => {
   const pathname = usePathname();
-  const isActive = props.items.some((item) => item.href === pathname);
-  return (
+  const isActive = props.items.some((item) => pathname === item.href || pathname.startsWith(`${item.href}/`));
+  const nav = (
     <NavLink label={props.label} leftSection={props.icon} defaultOpened={isActive}>
       {props.items.map((item) => (
         <NavLinkHref key={item.label} {...item} />
       ))}
     </NavLink>
   );
+  return <TourTarget id={props["data-onboarding-tour-id"]}>{nav}</TourTarget>;
 };
 
 interface CommonNavigationLinkProps {
   label: string;
   icon: ReactNode;
+  "data-onboarding-tour-id"?: string;
 }
 
 interface NavigationLinkHref extends CommonNavigationLinkProps {

apps/nextjs/src/components/layout/navigation.tsx

@@ -27,7 +27,7 @@ export const MainNavigation = ({ headerSection, footerSection, links }: MainNavi
             return null;
           }
 
-          const { icon: TablerIcon, iconProps, ...props } = link;
+          const { icon: TablerIcon, iconProps, "data-onboarding-tour-id": tourId, ...props } = link;
           const Icon =
             typeof TablerIcon === "string" ? (
               <Image src={TablerIcon} w={20} h={20} />
@@ -38,17 +38,20 @@ export const MainNavigation = ({ headerSection, footerSection, links }: MainNavi
           if ("items" in props) {
             clientLink = {
               ...props,
+              "data-onboarding-tour-id": tourId,
               items: props.items
                 .filter((item) => !item.hidden)
                 .map((item) => {
+                  const { "data-onboarding-tour-id": itemTourId, ...rest } = item;
                   return {
-                    ...item,
+                    ...rest,
+                    "data-onboarding-tour-id": itemTourId,
                     icon: <item.icon size={20} stroke={1.5} {...iconProps} />,
                   };
                 }),
             } as ClientNavigationLink;
           } else {
-            clientLink = props as ClientNavigationLink;
+            clientLink = { ...props, "data-onboarding-tour-id": tourId } as ClientNavigationLink;
           }
           return <CommonNavLink key={index} {...clientLink} icon={Icon} />;
         })}
@@ -63,6 +66,7 @@ interface CommonNavigationLinkProps {
   icon: TablerIcon | string;
   iconProps?: TablerIconProps;
   hidden?: boolean;
+  "data-onboarding-tour-id"?: string;
 }
 
 interface NavigationLinkHref extends CommonNavigationLinkProps {

apps/nextjs/src/components/navigation/dynamic-breadcrumb.tsx

@@ -58,19 +58,23 @@ export const DynamicBreadcrumb = ({
         }
         const href = `/${pathnameParts.slice(0, index + 1).join("/")}`;
         const translationKey = `${pathnameParts.slice(0, index + 1).join(".")}`;
+        const mappedValue = dynamicMappings?.get(pathnamePart);
+
+        if (mappedValue) {
+          if (nonInteractable?.includes(pathnamePart)) {
+            return <Text key={href}>{mappedValue}</Text>;
+          }
+          return (
+            <Anchor key={href} href={href}>
+              {mappedValue}
+            </Anchor>
+          );
+        }
 
         if (nonInteractable?.includes(pathnamePart)) {
           return <Text key={href}>{t(`${translationKey}.label` as TranslationKeys)}</Text>;
         }
 
-        if (dynamicMappings?.has(pathnamePart)) {
-          return (
-            <Anchor key={href} href={href}>
-              {dynamicMappings.get(pathnamePart)}
-            </Anchor>
-          );
-        }
-
         return (
           <Anchor key={href} href={href}>
             {t(`${translationKey}.label` as TranslationKeys)}

apps/nextjs/src/components/onboarding/board-tour.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useMemo } from "react";
+import type { OnboardingTourStep } from "@gfazioli/mantine-onboarding-tour";
+
+import { clientApi } from "@homarr/api/client";
+import { useRequiredBoard } from "@homarr/boards/context";
+import { createDocumentationLink } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import { useBoardPermissions } from "~/components/board/permissions/client";
+import { TourShell } from "./tour-shell";
+import { TourStepContent } from "./tour-step-content";
+
+export const BoardTourProvider = ({ children }: PropsWithChildren) => {
+  const t = useScopedI18n("onboardingTour.board");
+  const board = useRequiredBoard();
+  const { hasChangeAccess } = useBoardPermissions(board);
+  const utils = clientApi.useUtils();
+  const { data: tourStatus } = clientApi.user.getTourStatus.useQuery();
+  const { mutate: completeTour } = clientApi.user.completeTour.useMutation({
+    onSuccess() {
+      void utils.user.getTourStatus.invalidate();
+    },
+  });
+
+  const started = tourStatus !== undefined && !tourStatus.completedBoardTour;
+
+  const handleEnd = () => {
+    utils.user.getTourStatus.setData(undefined, {
+      completedManageTour: tourStatus?.completedManageTour ?? false,
+      completedBoardTour: true,
+    });
+    completeTour({ tour: "board" });
+  };
+
+  const steps = useMemo(() => {
+    const allSteps: (OnboardingTourStep & { requiresChangeAccess?: boolean })[] = [
+      {
+        id: "board-search",
+        title: t("welcome.title"),
+        content: (
+          <TourStepContent
+            description={t("welcome.description")}
+            documentationHref={createDocumentationLink(
+              "/docs/getting-started/after-the-installation",
+              "#creating-your-first-board",
+            )}
+          />
+        ),
+      },
+      {
+        id: "board-edit-mode",
+        title: t("editMode.title"),
+        requiresChangeAccess: true,
+        content: (
+          <TourStepContent
+            description={t("editMode.description")}
+            documentationHref={createDocumentationLink(
+              "/docs/getting-started/after-the-installation",
+              "#arrange-and-organize-your-board",
+            )}
+          />
+        ),
+      },
+      {
+        id: "board-settings",
+        title: t("settings.title"),
+        requiresChangeAccess: true,
+        content: (
+          <TourStepContent
+            description={t("settings.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+          />
+        ),
+      },
+      {
+        id: "board-switcher",
+        title: t("switcher.title"),
+        content: (
+          <TourStepContent
+            description={t("switcher.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+          />
+        ),
+      },
+      {
+        id: "board-user-menu",
+        title: t("userMenu.title"),
+        content: (
+          <TourStepContent
+            description={t("userMenu.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+          />
+        ),
+      },
+    ];
+
+    return allSteps.filter((step) => !step.requiresChangeAccess || hasChangeAccess) as OnboardingTourStep[];
+  }, [hasChangeAccess, t]);
+
+  return (
+    <TourShell steps={steps} started={started} onEnd={handleEnd} position={{ base: "bottom", sm: "left" }}>
+      {children}
+    </TourShell>
+  );
+};

apps/nextjs/src/components/onboarding/manage-tour.tsx

@@ -0,0 +1,220 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import type { OnboardingTourFocusRevealProps, OnboardingTourStep } from "@gfazioli/mantine-onboarding-tour";
+import { useMediaQuery } from "@mantine/hooks";
+import {
+  IconAffiliateFilled,
+  IconAppsFilled,
+  IconLayoutDashboardFilled,
+  IconPlus,
+  IconUserFilled,
+} from "@tabler/icons-react";
+
+import { clientApi } from "@homarr/api/client";
+import { createDocumentationLink } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import { TourShell } from "./tour-shell";
+import { TourStepContent } from "./tour-step-content";
+
+interface ManageTourProviderProps extends PropsWithChildren {
+  isAdmin: boolean;
+}
+
+const stepRoutes: Record<string, string> = {
+  "manage-welcome": "/manage",
+  "manage-boards-list": "/manage/boards",
+  "manage-boards-create": "/manage/boards",
+  "manage-apps-list": "/manage/apps",
+  "manage-apps-create": "/manage/apps",
+  "manage-integrations-list": "/manage/integrations",
+  "manage-integrations-create": "/manage/integrations",
+  "manage-users-list": "/manage/users",
+  "manage-users-create": "/manage/users",
+};
+
+const usersStepFocusRevealProps: OnboardingTourFocusRevealProps = {
+  withReveal: false,
+  popoverProps: {
+    position: "bottom",
+    middlewares: { shift: { padding: 16 }, flip: true },
+  },
+};
+
+export const ManageTourProvider = ({ children, isAdmin }: ManageTourProviderProps) => {
+  const t = useScopedI18n("onboardingTour.manage");
+  const utils = clientApi.useUtils();
+  const { data: tourStatus } = clientApi.user.getTourStatus.useQuery();
+  const { mutate: completeTour } = clientApi.user.completeTour.useMutation({
+    onSuccess() {
+      void utils.user.getTourStatus.invalidate();
+    },
+  });
+  const isMobile = useMediaQuery("(max-width: 48em)");
+  const pathname = usePathname();
+  const router = useRouter();
+
+  const isManageHome = /^(\/[^/]+)?\/manage\/?$/.test(pathname);
+  const isManageSection = /^(\/[^/]+)?\/manage(\/.*)?$/.test(pathname);
+
+  const [tourActive, setTourActive] = useState(false);
+  const [tourDismissed, setTourDismissed] = useState(false);
+  const wasManageTourCompletedRef = useRef(tourStatus?.completedManageTour);
+
+  useEffect(() => {
+    if (tourDismissed) return;
+    if (isManageHome && tourStatus !== undefined && !tourStatus.completedManageTour && !isMobile) {
+      setTourActive(true);
+    }
+  }, [isManageHome, tourStatus, isMobile, tourDismissed]);
+
+  useEffect(() => {
+    if (!isManageSection) {
+      setTourActive(false);
+    }
+  }, [isManageSection]);
+
+  useEffect(() => {
+    const wasCompleted = wasManageTourCompletedRef.current;
+    const isCompleted = tourStatus?.completedManageTour;
+    if (wasCompleted === true && isCompleted === false) {
+      setTourDismissed(false);
+    }
+    wasManageTourCompletedRef.current = isCompleted;
+  }, [tourStatus?.completedManageTour]);
+
+  const handleEnd = useCallback(() => {
+    setTourDismissed(true);
+    setTourActive(false);
+    utils.user.getTourStatus.setData(undefined, {
+      completedManageTour: true,
+      completedBoardTour: tourStatus?.completedBoardTour ?? false,
+    });
+    completeTour({ tour: "manage" });
+    router.push("/manage");
+  }, [completeTour, router, tourStatus?.completedBoardTour, utils.user.getTourStatus]);
+
+  const steps = useMemo(() => {
+    const allSteps: (OnboardingTourStep & { adminOnly?: boolean })[] = [
+      {
+        id: "manage-welcome",
+        title: t("welcome.title"),
+        content: (
+          <TourStepContent
+            description={t("welcome.description")}
+            documentationHref={createDocumentationLink("/docs/category/management")}
+          />
+        ),
+      },
+      {
+        id: "manage-boards-list",
+        title: t("boardsList.title"),
+        content: (
+          <TourStepContent
+            description={t("boardsList.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+            icon={<IconLayoutDashboardFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-boards-create",
+        title: t("boardsCreate.title"),
+        content: (
+          <TourStepContent
+            description={t("boardsCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/boards")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-apps-list",
+        title: t("appsList.title"),
+        content: (
+          <TourStepContent
+            description={t("appsList.description")}
+            documentationHref={createDocumentationLink("/docs/management/apps")}
+            icon={<IconAppsFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-apps-create",
+        title: t("appsCreate.title"),
+        content: (
+          <TourStepContent
+            description={t("appsCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/apps")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-integrations-list",
+        title: t("integrationsList.title"),
+        content: (
+          <TourStepContent
+            description={t("integrationsList.description")}
+            documentationHref={createDocumentationLink("/docs/management/integrations")}
+            icon={<IconAffiliateFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-integrations-create",
+        title: t("integrationsCreate.title"),
+        content: (
+          <TourStepContent
+            description={t("integrationsCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/integrations")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-users-list",
+        title: t("usersList.title"),
+        adminOnly: true,
+        focusRevealProps: usersStepFocusRevealProps,
+        content: (
+          <TourStepContent
+            description={t("usersList.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+            icon={<IconUserFilled size={18} />}
+          />
+        ),
+      },
+      {
+        id: "manage-users-create",
+        title: t("usersCreate.title"),
+        adminOnly: true,
+        focusRevealProps: usersStepFocusRevealProps,
+        content: (
+          <TourStepContent
+            description={t("usersCreate.description")}
+            documentationHref={createDocumentationLink("/docs/management/users")}
+            icon={<IconPlus size={18} />}
+          />
+        ),
+      },
+    ];
+
+    return allSteps.filter((step) => !step.adminOnly || isAdmin) as OnboardingTourStep[];
+  }, [isAdmin, t]);
+
+  return (
+    <TourShell
+      steps={steps}
+      started={tourActive}
+      onEnd={handleEnd}
+      stepRoutes={stepRoutes}
+      position={{ base: "bottom", sm: "right" }}
+    >
+      {children}
+    </TourShell>
+  );
+};

apps/nextjs/src/components/onboarding/tour-shell.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+import type { PropsWithChildren } from "react";
+import { useCallback, useEffect, useRef } from "react";
+import { useRouter } from "next/navigation";
+import type { OnboardingTourController, OnboardingTourStep } from "@gfazioli/mantine-onboarding-tour";
+import { OnboardingTour } from "@gfazioli/mantine-onboarding-tour";
+import { Button, Center, Group, Image, Kbd, Text } from "@mantine/core";
+import type { FloatingPosition } from "@mantine/core";
+
+import { useI18n } from "@homarr/translation/client";
+
+import { homarrLogoPath } from "~/components/layout/logo/homarr-logo";
+
+interface TourShellProps extends PropsWithChildren {
+  steps: OnboardingTourStep[];
+  started: boolean;
+  onEnd: () => void;
+  stepRoutes?: Record<string, string>;
+  position?: FloatingPosition | Record<string, FloatingPosition>;
+}
+
+type TourController = OnboardingTourController;
+
+const stepIndexFromController = (controller: TourController) => controller.currentStepIndex ?? 0;
+
+const stepAtOffset = (controller: TourController, offset: number) => {
+  const index = stepIndexFromController(controller) + offset;
+  return controller.tour[index];
+};
+
+const pollForElement = (targetId: string, callback: () => void) => {
+  const interval = setInterval(() => {
+    const targetElement = document.querySelector(`[data-tour-target="${targetId}"]`);
+    if (targetElement) {
+      clearInterval(interval);
+      callback();
+    }
+  }, 50);
+  const timeout = setTimeout(() => clearInterval(interval), 5000);
+  return () => {
+    clearInterval(interval);
+    clearTimeout(timeout);
+  };
+};
+
+const isTypingTarget = (target: EventTarget | null) => {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || target.isContentEditable;
+};
+
+interface TourForwardButtonProps {
+  label: string;
+  onClick: () => void;
+}
+
+const TourForwardButton = ({ label, onClick }: TourForwardButtonProps) => {
+  return (
+    <Button size="sm" variant="light" onClick={onClick} rightSection={<Kbd size="xs">↵</Kbd>}>
+      {label}
+    </Button>
+  );
+};
+
+interface TourDoneButtonProps {
+  label: string;
+  onClick: () => void;
+}
+
+const TourDoneButton = ({ label, onClick }: TourDoneButtonProps) => {
+  return (
+    <Button size="sm" onClick={onClick} rightSection={<Kbd size="xs">↵</Kbd>}>
+      {label}
+    </Button>
+  );
+};
+
+export const TourShell = ({ steps, started, onEnd, stepRoutes, position, children }: TourShellProps) => {
+  const t = useI18n();
+  const router = useRouter();
+  const forwardActionRef = useRef<(() => void) | null>(null);
+
+  const navigateAndAdvance = useCallback(
+    (currentStepId: string | undefined, targetStepId: string | undefined, advance: () => void) => {
+      if (!stepRoutes || !targetStepId) {
+        advance();
+        return;
+      }
+
+      const currentRoute = currentStepId ? stepRoutes[currentStepId] : undefined;
+      const targetRoute = stepRoutes[targetStepId];
+
+      if (targetRoute && targetRoute !== currentRoute) {
+        router.push(targetRoute);
+        pollForElement(targetStepId, advance);
+      } else {
+        advance();
+      }
+    },
+    [router, stepRoutes],
+  );
+
+  const bindForwardAction = useCallback((controller: TourController, action: () => void) => {
+    forwardActionRef.current = action;
+    return action;
+  }, []);
+
+  useEffect(() => {
+    if (!started) {
+      forwardActionRef.current = null;
+      return;
+    }
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Enter" || event.shiftKey || event.ctrlKey || event.metaKey || event.altKey) return;
+      if (isTypingTarget(event.target)) return;
+      event.preventDefault();
+      forwardActionRef.current?.();
+    };
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [started]);
+
+  return (
+    <OnboardingTour
+      tour={steps}
+      started={started}
+      onOnboardingTourEnd={onEnd}
+      withStepper={false}
+      header={(controller) => (
+        <>
+          <Group justify="center" gap={4} py={4}>
+            <Text size="sm" fw={600}>
+              {stepIndexFromController(controller) + 1}
+            </Text>
+            <Text size="sm" c="dimmed">
+              /
+            </Text>
+            <Text size="sm" c="dimmed">
+              {controller.tour.length}
+            </Text>
+          </Group>
+          {stepIndexFromController(controller) === 0 && (
+            <Center py="xs">
+              <Image src={homarrLogoPath} alt="Homarr" w={64} h={64} fit="contain" />
+            </Center>
+          )}
+        </>
+      )}
+      nextStepNavigation={(controller) => {
+        const nextStep = stepAtOffset(controller, 1);
+        const action = bindForwardAction(controller, () => {
+          navigateAndAdvance(controller.currentStep?.id, nextStep?.id, () => controller.nextStep());
+        });
+        return <TourForwardButton label={t("onboardingTour.next")} onClick={action} />;
+      }}
+      endStepNavigation={(controller) => {
+        const action = bindForwardAction(controller, () => controller.endTour());
+        return <TourDoneButton label={t("onboardingTour.done")} onClick={action} />;
+      }}
+      prevStepNavigation={(controller) => (
+        <Button
+          size="sm"
+          variant="default"
+          onClick={() => {
+            const prevStep = stepAtOffset(controller, -1);
+            navigateAndAdvance(controller.currentStep?.id, prevStep?.id, () => controller.prevStep());
+          }}
+        >
+          {t("onboardingTour.prev")}
+        </Button>
+      )}
+      skipNavigation={(controller) => (
+        <Button size="sm" variant="subtle" color="gray" onClick={() => controller.skipTour()}>
+          {t("onboardingTour.skip")}
+        </Button>
+      )}
+      withPrevButton
+      focusRevealProps={{
+        disableTargetInteraction: true,
+        popoverProps: {
+          position: position ?? { base: "bottom", sm: "right" },
+          width: 420,
+          shadow: "xl",
+          radius: "lg",
+          middlewares: { shift: { padding: 16 }, flip: true },
+        },
+      }}
+      cutoutPadding={12}
+      cutoutRadius={12}
+    >
+      {children}
+    </OnboardingTour>
+  );
+};

apps/nextjs/src/components/onboarding/tour-step-content.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { Anchor, Divider, Group, Stack, Text, ThemeIcon } from "@mantine/core";
+import { IconExternalLink } from "@tabler/icons-react";
+
+import { useI18n } from "@homarr/translation/client";
+
+interface TourStepContentProps {
+  description: string;
+  documentationHref: string;
+  icon?: ReactNode;
+}
+
+export const TourStepContent = ({ description, documentationHref, icon }: TourStepContentProps) => {
+  const t = useI18n();
+
+  return (
+    <Stack gap="sm">
+      <Group gap="sm" wrap="nowrap" align="flex-start">
+        {icon && (
+          <ThemeIcon variant="light" size="lg" radius="md" mt={2}>
+            {icon}
+          </ThemeIcon>
+        )}
+        <Text size="sm" lh={1.7} style={{ flex: 1 }}>
+          {description}
+        </Text>
+      </Group>
+      <Divider />
+      <Anchor href={documentationHref} target="_blank" size="xs" fw={500}>
+        <Group gap={4} wrap="nowrap">
+          <IconExternalLink size={14} />
+          {t("onboardingTour.learnMore")}
+        </Group>
+      </Anchor>
+    </Stack>
+  );
+};

e2e/onboarding.spec.ts

@@ -31,6 +31,7 @@ describe("Onboarding", () => {
       confirmPassword: "Comp(exP4sswOrd",
     });
     await actions.processSettingsStepAsync();
+    await actions.processIntegrationsStepAsync();
 
     // Assert
     await assertions.assertFinishStepVisibleAsync();
@@ -72,6 +73,7 @@ describe("Onboarding", () => {
       name: externalGroupName,
     });
     await actions.processSettingsStepAsync();
+    await actions.processIntegrationsStepAsync();
 
     // Assert
     await assertions.assertFinishStepVisibleAsync();

e2e/shared/actions/onboarding-actions.ts

@@ -51,4 +51,9 @@ export class OnboardingActions {
     await this.page.waitForSelector("text=Analytics");
     await this.page.locator("css=button[type='submit']").click();
   }
+
+  public async processIntegrationsStepAsync() {
+    await this.page.waitForSelector("text=integrations you'd like to connect");
+    await this.page.locator("button", { hasText: "Skip for now" }).click();
+  }
 }

e2e/shared/assertions/onboarding-assertions.ts

@@ -3,7 +3,7 @@ import { eq } from "drizzle-orm";
 import { expect } from "vitest";
 
 import * as sqliteSchema from "../../../packages/db/schema/sqlite";
-import { OnboardingStep } from "../../../packages/definitions/src";
+import type { OnboardingStep } from "../../../packages/definitions/src";
 import { credentialsAdminGroup } from "../../../packages/definitions/src/group";
 import type { SqliteDatabase } from "../e2e-db";
 
@@ -57,6 +57,6 @@ export class OnboardingAssertions {
   }
 
   public async assertFinishStepVisibleAsync() {
-    await this.page.waitForSelector("text=completed the setup", { timeout: 5000 });
+    await this.page.waitForSelector("text=completed the setup", { timeout: 15000 });
   }
 }

packages/api/package.json

@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client.ts",
+    "./query-cache": "./src/query-cache.ts",
     "./server": "./src/server.ts",
     "./websocket": "./src/websocket.ts",
     "./shared": "./src/shared.ts",

packages/api/src/query-cache.ts

@@ -0,0 +1,34 @@
+import type { QueryKey } from "@tanstack/react-query";
+
+export const queryCacheRetentionMs = 1000 * 60 * 60 * 24;
+export const queryCacheDefaultStaleTimeMs = 1000 * 60 * 5;
+export const queryCacheMaxValueBytes = 1024 * 1024;
+export const queryCacheStoragePrefix = "homarr-widget-query";
+
+let activeQueryCacheBoardId: string | null = null;
+
+export const setActiveQueryCacheBoardId = (boardId: string | null) => {
+  activeQueryCacheBoardId = boardId;
+};
+
+export const getActiveQueryCacheBoardId = () => activeQueryCacheBoardId;
+
+const persistableQueryPaths = new Set(["app.byId", "app.byIds", "docker.getContainers", "integration.byIds"]);
+const excludedWidgetPaths = new Set(["widget.app.ping"]);
+
+const getTrpcPathFromQueryKey = (queryKey: QueryKey) => {
+  const first = queryKey[0];
+  if (!Array.isArray(first)) return null;
+
+  const parts = first.filter((part): part is string => typeof part === "string");
+  return parts.length > 0 ? parts : null;
+};
+
+export const isPersistableWidgetQueryKey = (queryKey: QueryKey) => {
+  const path = getTrpcPathFromQueryKey(queryKey);
+  if (!path) return false;
+
+  if (path[0] === "widget") return !excludedWidgetPaths.has(path.join("."));
+
+  return persistableQueryPaths.has(path.join("."));
+};

packages/api/src/root.ts

@@ -24,6 +24,7 @@ export const appRouter = createTRPCRouter({
   cronJobs: lazy(() => import("./router/cron-jobs").then((mod) => mod.cronJobsRouter)),
   apiKeys: lazy(() => import("./router/apiKeys").then((mod) => mod.apiKeysRouter)),
   media: lazy(() => import("./router/medias/media-router").then((mod) => mod.mediaRouter)),
+  queryCache: lazy(() => import("./router/query-cache").then((mod) => mod.queryCacheRouter)),
   updateChecker: lazy(() => import("./router/update-checker").then((mod) => mod.updateCheckerRouter)),
   certificates: lazy(() => import("./router/certificates/certificate-router").then((mod) => mod.certificateRouter)),
   bangs: lazy(() => import("./router/bangs/bangs-router").then((mod) => mod.bangsRouter)),

packages/api/src/router/docker/docker-router.ts

@@ -4,7 +4,11 @@ import { z } from "zod/v4";
 
 import type { Container, ContainerState, Docker, Port } from "@homarr/docker";
 import { DockerSingleton } from "@homarr/docker";
-import { dockerContainersRequestHandler } from "@homarr/request-handler/docker";
+import {
+  dockerContainersRequestHandler,
+  getContainerLogsAsync,
+  streamContainerLogsAsync,
+} from "@homarr/request-handler/docker";
 
 import { dockerMiddleware } from "../../middlewares/docker";
 import { createTRPCRouter, permissionRequiredProcedure } from "../../trpc";
@@ -104,6 +108,84 @@ export const dockerRouter = createTRPCRouter({
       const innerHandler = dockerContainersRequestHandler.handler({});
       await innerHandler.invalidateAsync();
     }),
+  logs: permissionRequiredProcedure
+    .requiresPermission("admin")
+    .concat(dockerMiddleware())
+    .input(
+      z.object({
+        id: z.string(),
+        tail: z.number().min(1).max(1000).optional(),
+      }),
+    )
+    .query(async ({ input }) => {
+      const logs = await getContainerLogsAsync(input.id, input.tail ?? 200);
+
+      if (!logs) {
+        throw new TRPCError({
+          code: "NOT_FOUND",
+          message: "Container not found",
+        });
+      }
+
+      return {
+        logs,
+      };
+    }),
+  subscribeLogs: permissionRequiredProcedure
+    .requiresPermission("admin")
+    .concat(dockerMiddleware())
+    .input(
+      z.object({
+        id: z.string(),
+        tail: z.number().min(1).max(1000).optional(),
+      }),
+    )
+    .subscription(({ input }) => {
+      return observable<string>((emit) => {
+        let cleanupFn: (() => void) | undefined;
+        let isSubscribed = true;
+
+        const initializeStreamAsync = async () => {
+          try {
+            cleanupFn = await streamContainerLogsAsync(
+              input.id,
+              input.tail ?? 200,
+              (data) => {
+                if (isSubscribed) {
+                  emit.next(data);
+                }
+              },
+              (err) => {
+                if (isSubscribed) {
+                  emit.error(
+                    new TRPCError({
+                      code: "INTERNAL_SERVER_ERROR",
+                      message: err.message,
+                    }),
+                  );
+                }
+              },
+            );
+          } catch (err) {
+            if (isSubscribed) {
+              emit.error(
+                new TRPCError({
+                  code: "NOT_FOUND",
+                  message: err instanceof Error ? err.message : "Container not found",
+                }),
+              );
+            }
+          }
+        };
+
+        void initializeStreamAsync();
+
+        return () => {
+          isSubscribed = false;
+          cleanupFn?.();
+        };
+      });
+    }),
 });
 
 const getContainerOrDefaultAsync = async (instance: Docker, id: string) => {

packages/api/src/router/integration/integration-router.ts

@@ -1,6 +1,8 @@
 import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";
 
+import { hasQueryAccessToIntegrationsAsync } from "@homarr/auth/server";
+import { constructIntegrationPermissions } from "@homarr/auth/shared";
 import { createId, objectEntries } from "@homarr/common";
 import { decryptSecret, encryptSecret } from "@homarr/common/server";
 import { createLogger } from "@homarr/core/infrastructure/logs";
@@ -14,11 +16,9 @@ import {
   integrations,
   integrationSecrets,
   integrationUserPermissions,
-  searchEngines,
 } from "@homarr/db/schema";
 import type { IntegrationSecretKind } from "@homarr/definitions";
 import {
-  getIconUrl,
   getIntegrationKindsByCategory,
   getPermissionsWithParents,
   integrationCategories,
@@ -33,6 +33,7 @@ import {
   integrationSavePermissionsSchema,
   integrationUpdateSchema,
 } from "@homarr/validation/integration";
+import { mediaRequestOptionsSchema, mediaRequestRequestSchema } from "@homarr/validation/widgets/media-request";
 
 import { createOneIntegrationMiddleware } from "../../middlewares/integration";
 import { createTRPCRouter, permissionRequiredProcedure, protectedProcedure, publicProcedure } from "../../trpc";
@@ -41,6 +42,7 @@ import { MissingSecretError, testConnectionAsync } from "./integration-test-conn
 import { mapTestConnectionError } from "./map-test-connection-error";
 
 const logger = createLogger({ module: "integrationRouter" });
+const mediaRequestSearchKinds = getIntegrationKindsByCategory("mediaSearch");
 
 export const integrationRouter = createTRPCRouter({
   all: protectedProcedure.query(async ({ ctx }) => {
@@ -80,7 +82,7 @@ export const integrationRouter = createTRPCRouter({
           },
         };
       })
-      .sort(
+      .toSorted(
         (integrationA, integrationB) =>
           integrationKinds.indexOf(integrationA.kind) - integrationKinds.indexOf(integrationB.kind),
       );
@@ -128,7 +130,7 @@ export const integrationRouter = createTRPCRouter({
           },
         };
       })
-      .sort(
+      .toSorted(
         (integrationA, integrationB) =>
           integrationKinds.indexOf(integrationA.kind) - integrationKinds.indexOf(integrationB.kind),
       );
@@ -179,7 +181,7 @@ export const integrationRouter = createTRPCRouter({
             },
           };
         })
-        .sort(
+        .toSorted(
           (integrationA, integrationB) =>
             integrationKinds.indexOf(integrationA.kind) - integrationKinds.indexOf(integrationB.kind),
         );
@@ -314,20 +316,7 @@ export const integrationRouter = createTRPCRouter({
         url: input.url,
       });
 
-      if (
-        input.attemptSearchEngineCreation &&
-        integrationDefs[input.kind].category.flatMap((category) => category).includes("search")
-      ) {
-        const icon = getIconUrl(input.kind);
-        await ctx.db.insert(searchEngines).values({
-          id: createId(),
-          name: input.name,
-          integrationId,
-          type: "fromIntegration",
-          iconUrl: icon,
-          short: await getNextValidShortNameForSearchEngineAsync(ctx.db, input.name),
-        });
-      }
+      // Media request search is a first-class Spotlight action. Do not create a search engine for it.
     }),
   update: protectedProcedure.input(integrationUpdateSchema).mutation(async ({ ctx, input }) => {
     await throwIfActionForbiddenAsync(ctx, eq(integrations.id, input.id), "full");
@@ -495,7 +484,7 @@ export const integrationRouter = createTRPCRouter({
     });
 
     return {
-      inherited: dbGroupPermissions.sort((permissionA, permissionB) => {
+      inherited: dbGroupPermissions.toSorted((permissionA, permissionB) => {
         return permissionA.group.name.localeCompare(permissionB.group.name);
       }),
       users: userPermissions
@@ -503,7 +492,7 @@ export const integrationRouter = createTRPCRouter({
           user,
           permission,
         }))
-        .sort((permissionA, permissionB) => {
+        .toSorted((permissionA, permissionB) => {
           return (permissionA.user.name ?? "").localeCompare(permissionB.user.name ?? "");
         }),
       groups: dbGroupIntegrationPermission
@@ -514,7 +503,7 @@ export const integrationRouter = createTRPCRouter({
           },
           permission,
         }))
-        .sort((permissionA, permissionB) => {
+        .toSorted((permissionA, permissionB) => {
           return permissionA.group.name.localeCompare(permissionB.group.name);
         }),
     };
@@ -618,8 +607,149 @@ export const integrationRouter = createTRPCRouter({
       const integrationInstance = await createIntegrationAsync(ctx.integration);
       return await integrationInstance.searchAsync(encodeURI(input.query));
     }),
+  mediaRequestSearchTargets: protectedProcedure.query(async ({ ctx }) => {
+    const integrationsWithAccess = await getAccessibleMediaRequestSearchIntegrationsAsync(ctx);
+
+    return integrationsWithAccess.map((integration) => {
+      const permissions = constructIntegrationPermissions(integration, ctx.session);
+
+      return {
+        id: integration.id,
+        name: integration.name,
+        kind: integration.kind,
+        url: integration.url,
+        permissions: {
+          hasInteractAccess: permissions.hasInteractAccess,
+        },
+      };
+    });
+  }),
+  searchMediaRequests: protectedProcedure
+    .input(
+      z.object({
+        query: z.string(),
+        integrationIds: z.array(z.string()).optional(),
+      }),
+    )
+    .query(async ({ ctx, input }) => {
+      const query = input.query.trim();
+      if (query.length === 0) return [];
+
+      const integrationsWithAccess = await getAccessibleMediaRequestSearchIntegrationsAsync(ctx, input.integrationIds);
+
+      const results = await Promise.all(
+        integrationsWithAccess.map(async (integration) => {
+          const integrationInstance = await createIntegrationAsync({
+            id: integration.id,
+            name: integration.name,
+            url: integration.url,
+            kind: integration.kind as (typeof mediaRequestSearchKinds)[number],
+            externalUrl: integration.app?.href ?? null,
+            decryptedSecrets: integration.secrets.map((secret) => ({
+              ...secret,
+              value: decryptSecret(secret.value),
+            })),
+          });
+          const permissions = constructIntegrationPermissions(integration, ctx.session);
+
+          return await integrationInstance.searchAsync(encodeURI(query)).then((searchResults) =>
+            searchResults.map((result) => ({
+              ...result,
+              integration: {
+                id: integration.id,
+                name: integration.name,
+                kind: integration.kind,
+                url: integration.url,
+                permissions: {
+                  hasInteractAccess: permissions.hasInteractAccess,
+                },
+              },
+            })),
+          );
+        }),
+      );
+
+      return results.flat();
+    }),
+  getMediaRequestOptions: protectedProcedure
+    .concat(createOneIntegrationMiddleware("query", "jellyseerr", "overseerr", "seerr"))
+    .input(mediaRequestOptionsSchema)
+    .query(async ({ ctx, input }) => {
+      const integration = await createIntegrationAsync(ctx.integration);
+      return await integration.getSeriesInformationAsync(input.mediaType, input.mediaId);
+    }),
+  requestMedia: protectedProcedure
+    .concat(createOneIntegrationMiddleware("interact", "jellyseerr", "overseerr", "seerr"))
+    .input(mediaRequestRequestSchema)
+    .mutation(async ({ ctx, input }) => {
+      const integration = await createIntegrationAsync(ctx.integration);
+      return await integration.requestMediaAsync(input.mediaType, input.mediaId, input.seasons);
+    }),
 });
 
+interface IntegrationRouterContext {
+  db: Database;
+  session: Parameters<typeof hasQueryAccessToIntegrationsAsync>[2];
+}
+
+const getAccessibleMediaRequestSearchIntegrationsAsync = async (
+  ctx: IntegrationRouterContext,
+  integrationIds?: string[],
+) => {
+  const groupsOfCurrentUser = await ctx.db.query.groupMembers.findMany({
+    where: eq(groupMembers.userId, ctx.session?.user.id ?? ""),
+  });
+
+  const integrationsFromDb = await ctx.db.query.integrations.findMany({
+    where:
+      integrationIds && integrationIds.length > 0
+        ? and(inArray(integrations.id, integrationIds), inArray(integrations.kind, mediaRequestSearchKinds))
+        : inArray(integrations.kind, mediaRequestSearchKinds),
+    orderBy: asc(integrations.name),
+    with: {
+      app: true,
+      secrets: true,
+      items: {
+        with: {
+          item: true,
+        },
+      },
+      userPermissions: {
+        where: eq(integrationUserPermissions.userId, ctx.session?.user.id ?? ""),
+      },
+      groupPermissions: {
+        where: inArray(
+          integrationGroupPermissions.groupId,
+          groupsOfCurrentUser.map((group) => group.groupId),
+        ),
+      },
+    },
+  });
+
+  if (integrationIds && integrationsFromDb.length !== integrationIds.length) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "One or more media request search integrations were not found",
+    });
+  }
+
+  const integrationsWithAccess = await Promise.all(
+    integrationsFromDb.map(async (integration) => ({
+      integration,
+      hasAccess: await hasQueryAccessToIntegrationsAsync(ctx.db, [integration], ctx.session),
+    })),
+  );
+
+  if (integrationIds && integrationsWithAccess.some(({ hasAccess }) => !hasAccess)) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "User does not have permission to query one or more media request search integrations",
+    });
+  }
+
+  return integrationsWithAccess.filter(({ hasAccess }) => hasAccess).map(({ integration }) => integration);
+};
+
 interface UpdateSecretInput {
   integrationId: string;
   value: string;
@@ -640,35 +770,6 @@ interface AddSecretInput {
   kind: IntegrationSecretKind;
 }
 
-const getNextValidShortNameForSearchEngineAsync = async (db: Database, integrationName: string) => {
-  const searchEngines = await db.query.searchEngines.findMany({
-    columns: {
-      short: true,
-    },
-  });
-
-  const usedShortNames = searchEngines.flatMap((searchEngine) => searchEngine.short.toLowerCase());
-  const nameByIntegrationName = integrationName.slice(0, 1).toLowerCase();
-
-  if (!usedShortNames.includes(nameByIntegrationName)) {
-    return nameByIntegrationName;
-  }
-
-  // 8 is max length constraint
-  for (let i = 2; i < 9999999; i++) {
-    const generatedName = `${nameByIntegrationName}${i}`;
-    if (usedShortNames.includes(generatedName)) {
-      continue;
-    }
-
-    return generatedName;
-  }
-
-  throw new Error(
-    "Unable to automatically generate a short name. All possible variations were exhausted. Please disable the automatic creation and choose one later yourself.",
-  );
-};
-
 const addSecretAsync = async (db: Database, input: AddSecretInput) => {
   await db.insert(integrationSecrets).values({
     kind: input.kind,

packages/api/src/router/onboard/onboard-queries.ts

@@ -76,6 +76,9 @@ const nextSteps: Partial<Record<OnboardingStep, Partial<Record<OnboardingStep, N
     settings: true,
   },
   settings: {
+    integrations: true,
+  },
+  integrations: {
     finish: true,
   },
 };

packages/api/src/router/onboard/onboard-router.ts

@@ -1,12 +1,57 @@
+import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";
 
-import { onboarding } from "@homarr/db/schema";
-import { onboardingSteps } from "@homarr/definitions";
+import { createId } from "@homarr/common";
+import { encryptSecret } from "@homarr/common/server";
+import { eq, like, or } from "@homarr/db";
+import { placeAllWidgetsAsync } from "@homarr/db/queries";
+import {
+  apps,
+  groups,
+  icons,
+  integrationItems,
+  integrations,
+  integrationSecrets,
+  itemLayouts,
+  items,
+  onboarding,
+} from "@homarr/db/schema";
+import {
+  everyoneGroup,
+  extractContainerImageName,
+  getIconUrl,
+  integrationKinds,
+  integrationSecretKinds,
+  matchIntegrationKindFromContainer,
+  onboardingSteps,
+} from "@homarr/definitions";
+import type { IntegrationKind } from "@homarr/definitions";
 import { zodEnumFromArray } from "@homarr/validation/enums";
 
-import { createTRPCRouter, publicProcedure } from "../../trpc";
+import { createTRPCRouter, onboardingProcedure, publicProcedure } from "../../trpc";
+import { MissingSecretError, testConnectionAsync } from "../integration/integration-test-connection";
+import { mapTestConnectionError } from "../integration/map-test-connection-error";
 import { getOnboardingOrFallbackAsync, nextOnboardingStepAsync } from "./onboard-queries";
 
+interface PortInfo {
+  IP?: string;
+  PublicPort?: number;
+}
+
+interface SuggestedUrlResult {
+  url: string;
+  publishedPort: number | null;
+}
+
+const buildSuggestedUrl = (ports: PortInfo[] | undefined, host: string): SuggestedUrlResult => {
+  const port = ports?.[0];
+  if (port?.PublicPort) {
+    const ip = port.IP && port.IP !== "0.0.0.0" && port.IP !== "::" ? port.IP : host;
+    return { url: `http://${ip}:${port.PublicPort}`, publishedPort: port.PublicPort };
+  }
+  return { url: "", publishedPort: null };
+};
+
 export const onboardRouter = createTRPCRouter({
   currentStep: publicProcedure.query(async ({ ctx }) => {
     return await getOnboardingOrFallbackAsync(ctx.db);
@@ -33,4 +78,249 @@ export const onboardRouter = createTRPCRouter({
       step: "start",
     });
   }),
+  createIntegration: onboardingProcedure
+    .requiresStep("integrations")
+    .input(
+      z.object({
+        name: z.string().nonempty().max(127),
+        url: z.string().nonempty(),
+        kind: zodEnumFromArray(integrationKinds),
+        secrets: z.array(
+          z.object({
+            kind: zodEnumFromArray(integrationSecretKinds),
+            value: z.string().nonempty(),
+          }),
+        ),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const result = await testConnectionAsync({
+        id: "new",
+        name: input.name,
+        url: input.url,
+        kind: input.kind,
+        secrets: input.secrets,
+      }).catch((error) => {
+        if (!(error instanceof MissingSecretError)) throw error;
+
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: error.message,
+        });
+      });
+
+      if (!result.success) {
+        return { error: mapTestConnectionError(result.error) };
+      }
+
+      const integrationId = createId();
+      const appId = createId();
+
+      await ctx.db.insert(apps).values({
+        id: appId,
+        name: input.name,
+        iconUrl: getIconUrl(input.kind),
+        href: input.url,
+        pingUrl: input.url,
+        description: null,
+      });
+
+      await ctx.db.insert(integrations).values({
+        id: integrationId,
+        name: input.name,
+        url: input.url,
+        kind: input.kind,
+        appId,
+      });
+
+      if (input.secrets.length >= 1) {
+        await ctx.db.insert(integrationSecrets).values(
+          input.secrets.map((secret) => ({
+            kind: secret.kind,
+            value: encryptSecret(secret.value),
+            integrationId,
+          })),
+        );
+      }
+    }),
+  discoverDockerServices: onboardingProcedure.requiresStep("integrations").query(async ({ ctx }) => {
+    const emptyResult = {
+      integrations: [] as {
+        containerId: string;
+        containerName: string;
+        kind: IntegrationKind;
+        suggestedUrl: string;
+        publishedPort: number | null;
+        iconUrl: string | null;
+      }[],
+      apps: [] as {
+        containerId: string;
+        containerName: string;
+        suggestedUrl: string;
+        publishedPort: number | null;
+        iconUrl: string | null;
+      }[],
+    };
+
+    try {
+      const { DockerSingleton, dockerLabels } = await import("@homarr/docker");
+
+      const dockerInstances = DockerSingleton.getInstances();
+      if (dockerInstances.length === 0) {
+        return { status: "empty" as const, ...emptyResult };
+      }
+
+      const results = await Promise.allSettled(
+        dockerInstances.map(async ({ instance, host }) => {
+          const containerList = await instance.listContainers({ all: false });
+          return containerList.filter((c) => !(dockerLabels.hide in c.Labels)).map((c) => ({ ...c, host }));
+        }),
+      );
+
+      const containers = results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+
+      if (containers.length === 0) {
+        return { status: "empty" as const, ...emptyResult };
+      }
+
+      const likeQueries = containers.map((c) => like(icons.name, `%${extractContainerImageName(c.Image)}%`));
+      const dbIcons = likeQueries.length > 0 ? await ctx.db.query.icons.findMany({ where: or(...likeQueries) }) : [];
+
+      const seenKinds = new Set<IntegrationKind>();
+      const discoveredIntegrations = emptyResult.integrations;
+      const discoveredApps = emptyResult.apps;
+
+      const cdnIconUrl = (slug: string) =>
+        `https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/${slug}.svg`;
+
+      const strictIconMatch = (imageName: string) => {
+        const normalized = imageName.toLowerCase().trim();
+        if (normalized.length < 3) return null;
+        const exact = dbIcons.find((icon) => icon.name.toLowerCase() === normalized);
+        if (exact) return exact.url;
+        return dbIcons.find((icon) => icon.name.toLowerCase().startsWith(normalized))?.url ?? null;
+      };
+
+      for (const container of containers) {
+        const imageName = extractContainerImageName(container.Image);
+        const containerName = container.Names[0]?.split("/")[1] ?? "Unknown";
+        const dbIcon = strictIconMatch(imageName);
+        const iconUrl = dbIcon ?? cdnIconUrl(imageName.toLowerCase());
+
+        const { url: suggestedUrl, publishedPort } = buildSuggestedUrl(container.Ports, container.host);
+
+        const kind = matchIntegrationKindFromContainer({
+          image: container.Image,
+          name: containerName,
+        });
+
+        if (kind && !seenKinds.has(kind)) {
+          seenKinds.add(kind);
+          discoveredIntegrations.push({
+            containerId: container.Id,
+            containerName,
+            kind,
+            suggestedUrl,
+            publishedPort,
+            iconUrl,
+          });
+        } else if (!kind && dbIcon) {
+          discoveredApps.push({
+            containerId: container.Id,
+            containerName,
+            suggestedUrl,
+            publishedPort,
+            iconUrl,
+          });
+        }
+      }
+
+      return {
+        status: "success" as const,
+        integrations: discoveredIntegrations,
+        apps: discoveredApps,
+      };
+    } catch {
+      return { status: "unavailable" as const, ...emptyResult };
+    }
+  }),
+  createAppsFromDiscovery: onboardingProcedure
+    .requiresStep("integrations")
+    .input(
+      z.array(
+        z.object({
+          name: z.string().nonempty().max(127),
+          href: z.string().nullable(),
+          iconUrl: z.string().nullable(),
+        }),
+      ),
+    )
+    .mutation(async ({ ctx, input }) => {
+      if (input.length === 0) return;
+      const defaultIcon = "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/homarr.svg";
+      await ctx.db.insert(apps).values(
+        input.map((app) => ({
+          id: createId(),
+          name: app.name,
+          iconUrl: app.iconUrl ?? defaultIcon,
+          href: app.href,
+          description: null,
+        })),
+      );
+    }),
+  setupIntegrations: onboardingProcedure.requiresStep("integrations").mutation(async ({ ctx }) => {
+    const db = ctx.db;
+
+    const allIntegrations = await db.query.integrations.findMany();
+    const allApps = await db.query.apps.findMany();
+
+    const board = await db.query.boards.findFirst({
+      with: {
+        sections: true,
+        layouts: true,
+      },
+    });
+
+    if (!board) {
+      await nextOnboardingStepAsync(db, undefined);
+      return;
+    }
+
+    const everyoneGroupRow = await db.query.groups.findFirst({
+      where: eq(groups.name, everyoneGroup),
+    });
+    if (everyoneGroupRow && !everyoneGroupRow.homeBoardId) {
+      await db.update(groups).set({ homeBoardId: board.id }).where(eq(groups.id, everyoneGroupRow.id));
+    }
+
+    const section = board.sections.find((boardSection) => boardSection.kind === "empty");
+    const layout = board.layouts[0];
+
+    if (section && layout) {
+      const existingItems = await db.query.items.findMany({
+        where: eq(items.boardId, board.id),
+      });
+      for (const item of existingItems) {
+        await db.delete(integrationItems).where(eq(integrationItems.itemId, item.id));
+        await db.delete(itemLayouts).where(eq(itemLayouts.itemId, item.id));
+      }
+      if (existingItems.length > 0) {
+        await db.delete(items).where(eq(items.boardId, board.id));
+      }
+
+      await placeAllWidgetsAsync(
+        db,
+        {
+          boardId: board.id,
+          sectionId: section.id,
+          layoutId: layout.id,
+          columnCount: layout.columnCount,
+        },
+        allIntegrations,
+        allApps,
+      );
+    }
+
+    await nextOnboardingStepAsync(db, undefined);
+  }),
 });

packages/api/src/router/query-cache.ts

@@ -0,0 +1,54 @@
+import { z } from "zod/v4";
+
+import { eq } from "@homarr/db";
+import { boards } from "@homarr/db/schema";
+import { createQueryCacheChannel } from "@homarr/redis";
+
+import { queryCacheMaxValueBytes, queryCacheRetentionMs } from "../query-cache";
+import { createTRPCRouter, publicProcedure } from "../trpc";
+import { throwIfActionForbiddenAsync } from "./board/board-access";
+
+const queryCacheKeyInput = z.object({
+  boardId: z.string().min(1),
+  key: z.string().min(1).max(4096),
+});
+
+const queryCacheSetInput = queryCacheKeyInput.extend({
+  value: z.string().max(queryCacheMaxValueBytes * 2),
+});
+
+const createChannel = (input: z.infer<typeof queryCacheKeyInput>, userId: string) =>
+  createQueryCacheChannel({
+    userId,
+    boardId: input.boardId,
+    key: input.key,
+    ttlMs: queryCacheRetentionMs,
+    maxValueBytes: queryCacheMaxValueBytes,
+  });
+
+const validateBoardAccessAsync = async (ctx: Parameters<typeof throwIfActionForbiddenAsync>[0], boardId: string) => {
+  await throwIfActionForbiddenAsync(ctx, eq(boards.id, boardId), "view");
+};
+
+export const queryCacheRouter = createTRPCRouter({
+  getItem: publicProcedure.input(queryCacheKeyInput).query(async ({ ctx, input }) => {
+    await validateBoardAccessAsync(ctx, input.boardId);
+
+    const channel = createChannel(input, ctx.session?.user.id ?? "anonymous");
+    return await channel.getAsync();
+  }),
+  setItem: publicProcedure.input(queryCacheSetInput).mutation(async ({ ctx, input }) => {
+    await validateBoardAccessAsync(ctx, input.boardId);
+
+    const channel = createChannel(input, ctx.session?.user.id ?? "anonymous");
+    return {
+      stored: await channel.setAsync(input.value),
+    };
+  }),
+  removeItem: publicProcedure.input(queryCacheKeyInput).mutation(async ({ ctx, input }) => {
+    await validateBoardAccessAsync(ctx, input.boardId);
+
+    const channel = createChannel(input, ctx.session?.user.id ?? "anonymous");
+    await channel.removeAsync();
+  }),
+});

packages/api/src/router/search-engine/search-engine-router.ts

@@ -6,12 +6,9 @@ import { createLogger } from "@homarr/core/infrastructure/logs";
 import { asc, eq, like } from "@homarr/db";
 import { getServerSettingByKeyAsync, updateServerSettingByKeyAsync } from "@homarr/db/queries";
 import { searchEngines, users } from "@homarr/db/schema";
-import { createIntegrationAsync } from "@homarr/integrations";
 import { byIdSchema, paginatedSchema, searchSchema } from "@homarr/validation/common";
 import { searchEngineEditSchema, searchEngineManageSchema } from "@homarr/validation/search-engine";
-import { mediaRequestOptionsSchema, mediaRequestRequestSchema } from "@homarr/validation/widgets/media-request";
 
-import { createOneIntegrationMiddleware } from "../../middlewares/integration";
 import { createTRPCRouter, permissionRequiredProcedure, protectedProcedure, publicProcedure } from "../../trpc";
 
 const logger = createLogger({ module: "searchEngineRouter" });
@@ -148,20 +145,6 @@ export const searchEngineRouter = createTRPCRouter({
       limit: input.limit,
     });
   }),
-  getMediaRequestOptions: protectedProcedure
-    .concat(createOneIntegrationMiddleware("query", "jellyseerr", "overseerr"))
-    .input(mediaRequestOptionsSchema)
-    .query(async ({ ctx, input }) => {
-      const integration = await createIntegrationAsync(ctx.integration);
-      return await integration.getSeriesInformationAsync(input.mediaType, input.mediaId);
-    }),
-  requestMedia: protectedProcedure
-    .concat(createOneIntegrationMiddleware("interact", "jellyseerr", "overseerr"))
-    .input(mediaRequestRequestSchema)
-    .mutation(async ({ ctx, input }) => {
-      const integration = await createIntegrationAsync(ctx.integration);
-      return await integration.requestMediaAsync(input.mediaType, input.mediaId, input.seasons);
-    }),
   create: permissionRequiredProcedure
     .requiresPermission("search-engine-create")
     .input(searchEngineManageSchema)

packages/api/src/router/test/docker/docker-router.spec.ts

@@ -13,6 +13,14 @@ import { dockerRouter } from "../../docker/docker-router";
 // Mock the auth module to return an empty session
 vi.mock("@homarr/auth", () => ({ auth: () => ({}) as Session }));
 vi.mock("@homarr/request-handler/docker", () => ({
+  getContainerLogsAsync: async () => {
+    await Promise.resolve();
+    return "logs";
+  },
+  streamContainerLogsAsync: async () => {
+    await Promise.resolve();
+    return () => undefined;
+  },
   dockerContainersRequestHandler: {
     handler: () => ({
       getCachedOrUpdatedDataAsync: async () => {
@@ -65,6 +73,8 @@ const validInputs: {
   restartAll: { ids: ["1"] },
   removeAll: { ids: ["1"] },
   invalidate: undefined,
+  logs: { id: "1", tail: 200 },
+  subscribeLogs: { id: "1", tail: 200 },
 };
 
 describe("All procedures should only be accessible for users with admin permission", () => {

packages/api/src/router/test/integration/integration-router.spec.ts

@@ -4,7 +4,7 @@ import { describe, expect, test, vi } from "vitest";
 import type { Session } from "@homarr/auth";
 import { createId } from "@homarr/common";
 import { encryptSecret } from "@homarr/common/server";
-import { apps, integrations, integrationSecrets } from "@homarr/db/schema";
+import { apps, integrations, integrationSecrets, integrationUserPermissions, users } from "@homarr/db/schema";
 import { createDb } from "@homarr/db/test";
 import type { GroupPermissionKey } from "@homarr/definitions";
 
@@ -59,6 +59,127 @@ describe("all should return all integrations", () => {
   });
 });
 
+describe("mediaRequestSearchTargets should return accessible media search integrations", () => {
+  test("with integration use access should only return media request search integrations", async () => {
+    const db = createDb();
+    const caller = integrationRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSessionWithPermissions(["integration-use-all"]),
+    });
+
+    await db.insert(integrations).values([
+      {
+        id: "1",
+        name: "Jellyseerr",
+        kind: "jellyseerr",
+        url: "http://jellyseerr.local",
+      },
+      {
+        id: "2",
+        name: "Jellyfin",
+        kind: "jellyfin",
+        url: "http://jellyfin.local",
+      },
+    ]);
+
+    const result = await caller.mediaRequestSearchTargets();
+
+    expect(result).toHaveLength(1);
+    expect(result[0]!.id).toBe("1");
+    expect(result[0]!.kind).toBe("jellyseerr");
+  });
+
+  test("without access should not return media request search integrations", async () => {
+    const db = createDb();
+    const caller = integrationRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSessionWithPermissions(),
+    });
+
+    await db.insert(integrations).values({
+      id: "1",
+      name: "Jellyseerr",
+      kind: "jellyseerr",
+      url: "http://jellyseerr.local",
+    });
+
+    const result = await caller.mediaRequestSearchTargets();
+
+    expect(result).toHaveLength(0);
+  });
+
+  test("with direct integration use access should return media request search integrations", async () => {
+    const db = createDb();
+    const caller = integrationRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSessionWithPermissions(),
+    });
+
+    await db.insert(integrations).values({
+      id: "1",
+      name: "Jellyseerr",
+      kind: "jellyseerr",
+      url: "http://jellyseerr.local",
+    });
+    await db.insert(users).values({ id: defaultUserId });
+    await db.insert(integrationUserPermissions).values({
+      integrationId: "1",
+      userId: defaultUserId,
+      permission: "use",
+    });
+
+    const result = await caller.mediaRequestSearchTargets();
+
+    expect(result).toHaveLength(1);
+    expect(result[0]!.id).toBe("1");
+  });
+});
+
+describe("searchMediaRequests should validate scoped integrations", () => {
+  test("with a non media search integration should throw not found", async () => {
+    const db = createDb();
+    const caller = integrationRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSessionWithPermissions(["integration-use-all"]),
+    });
+
+    await db.insert(integrations).values({
+      id: "1",
+      name: "Jellyfin",
+      kind: "jellyfin",
+      url: "http://jellyfin.local",
+    });
+
+    await expect(caller.searchMediaRequests({ query: "matrix", integrationIds: ["1"] })).rejects.toThrow(
+      "One or more media request search integrations were not found",
+    );
+  });
+
+  test("without query access to a scoped media search integration should throw forbidden", async () => {
+    const db = createDb();
+    const caller = integrationRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSessionWithPermissions(),
+    });
+
+    await db.insert(integrations).values({
+      id: "1",
+      name: "Jellyseerr",
+      kind: "jellyseerr",
+      url: "http://jellyseerr.local",
+    });
+
+    await expect(caller.searchMediaRequests({ query: "matrix", integrationIds: ["1"] })).rejects.toThrow(
+      "User does not have permission to query one or more media request search integrations",
+    );
+  });
+});
+
 describe("byId should return an integration by id", () => {
   test("with full access should return an integration by id", async () => {
     const db = createDb();
@@ -208,7 +329,7 @@ describe("create should create a new integration", () => {
     expect(dbSecret!.updatedAt).toEqual(fakeNow);
   });
 
-  test("with create integration access should create a new integration when creating search engine", async () => {
+  test("with create integration access should not create a search engine for media request search integrations", async () => {
     const db = createDb();
     const caller = integrationRouter.createCaller({
       db,
@@ -243,12 +364,7 @@ describe("create should create a new integration", () => {
     expect(dbSecret!.value).toMatch(/^[a-f0-9]+.[a-f0-9]+$/);
     expect(dbSecret!.updatedAt).toEqual(fakeNow);
 
-    expect(dbSearchEngine!.integrationId).toBe(dbIntegration!.id);
-    expect(dbSearchEngine!.short).toBe("j");
-    expect(dbSearchEngine!.name).toBe(input.name);
-    expect(dbSearchEngine!.iconUrl).toBe(
-      "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/jellyseerr.svg",
-    );
+    expect(dbSearchEngine).toBeUndefined();
   });
 
   test("with create integration access should create a new integration with new linked app", async () => {

packages/api/src/router/user.ts

@@ -278,6 +278,8 @@ export const userRouter = createTRPCRouter({
         defaultSearchEngineId: true,
         openSearchInNewTab: true,
         ddgBangs: true,
+        completedManageTour: true,
+        completedBoardTour: true,
       }),
     )
     .meta({ openapi: { method: "GET", path: "/api/users/{userId}", tags: ["users"], protect: true } })
@@ -304,6 +306,8 @@ export const userRouter = createTRPCRouter({
           defaultSearchEngineId: true,
           openSearchInNewTab: true,
           ddgBangs: true,
+          completedManageTour: true,
+          completedBoardTour: true,
         },
         where: eq(users.id, input.userId),
       });
@@ -542,7 +546,7 @@ export const userRouter = createTRPCRouter({
         .set({
           pingIconsEnabled: input.pingIconsEnabled,
         })
-        .where(eq(users.id, ctx.session.user.id));
+        .where(eq(users.id, input.id));
     }),
   changeDdgBangs: protectedProcedure
     .input(convertIntersectionToZodObject(userDdgBangsSchema.and(byIdSchema)))
@@ -603,8 +607,41 @@ export const userRouter = createTRPCRouter({
         .set({
           firstDayOfWeek: input.firstDayOfWeek,
         })
-        .where(eq(users.id, ctx.session.user.id));
+        .where(eq(users.id, input.id));
     }),
+  completeTour: protectedProcedure
+    .input(z.object({ tour: z.enum(["manage", "board"]) }))
+    .mutation(async ({ input, ctx }) => {
+      const columnByTour = {
+        manage: { completedManageTour: true },
+        board: { completedBoardTour: true },
+      } as const;
+
+      await ctx.db.update(users).set(columnByTour[input.tour]).where(eq(users.id, ctx.session.user.id));
+    }),
+  resetTours: protectedProcedure.mutation(async ({ ctx }) => {
+    await ctx.db
+      .update(users)
+      .set({
+        completedManageTour: false,
+        completedBoardTour: false,
+      })
+      .where(eq(users.id, ctx.session.user.id));
+  }),
+  getTourStatus: protectedProcedure.query(async ({ ctx }) => {
+    const user = await ctx.db.query.users.findFirst({
+      columns: {
+        completedManageTour: true,
+        completedBoardTour: true,
+      },
+      where: eq(users.id, ctx.session.user.id),
+    });
+
+    return {
+      completedManageTour: user?.completedManageTour ?? false,
+      completedBoardTour: user?.completedBoardTour ?? false,
+    };
+  }),
 });
 
 const createUserAsync = async (db: Database, input: Omit<z.infer<typeof userBaseCreateSchema>, "groupIds">) => {

packages/api/src/shared.ts

@@ -1,5 +1,7 @@
 import { defaultShouldDehydrateQuery, QueryClient } from "@tanstack/react-query";
 
+import { queryCacheDefaultStaleTimeMs } from "./query-cache";
+
 /**
  * Creates a headers callback for a given source
  * It will set the x-trpc-source header and cookies if needed
@@ -58,7 +60,7 @@ export const makeQueryClient = () => {
   return new QueryClient({
     defaultOptions: {
       queries: {
-        staleTime: 5 * 1000,
+        staleTime: queryCacheDefaultStaleTimeMs,
       },
       dehydrate: {
         shouldDehydrateQuery: (query) => defaultShouldDehydrateQuery(query) || query.state.status === "pending",

packages/api/src/test/query-cache.spec.ts

@@ -0,0 +1,224 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { QueryClient } from "@tanstack/react-query";
+
+import type { Session } from "@homarr/auth";
+import { createId } from "@homarr/common";
+import type { Database } from "@homarr/db";
+import { boards, users } from "@homarr/db/schema";
+import { createDb } from "@homarr/db/test";
+import {
+  isPersistableWidgetQueryKey,
+  queryCacheDefaultStaleTimeMs,
+  queryCacheMaxValueBytes,
+  queryCacheRetentionMs,
+} from "@homarr/api/query-cache";
+
+import { queryCacheRouter } from "../router/query-cache";
+
+const redisMock = vi.hoisted(() => {
+  const values = new Map<string, { value: string; expiresAt: number }>();
+  const calls: {
+    userId: string;
+    boardId: string;
+    key: string;
+    ttlMs: number;
+    maxValueBytes: number;
+  }[] = [];
+
+  return {
+    values,
+    calls,
+    createQueryCacheChannel: vi.fn(
+      (options: { userId: string; boardId: string; key: string; ttlMs: number; maxValueBytes: number }) => {
+        calls.push(options);
+        const storageKey = `${options.userId}:${options.boardId}:${options.key}`;
+
+        return {
+          getAsync: async () => {
+            const item = values.get(storageKey);
+            if (!item) return null;
+            if (Date.now() > item.expiresAt) {
+              values.delete(storageKey);
+              return null;
+            }
+
+            return item.value;
+          },
+          setAsync: async (value: string) => {
+            if (Buffer.byteLength(value, "utf8") > options.maxValueBytes) {
+              return false;
+            }
+
+            values.set(storageKey, { value, expiresAt: Date.now() + options.ttlMs });
+            return true;
+          },
+          removeAsync: async () => {
+            values.delete(storageKey);
+          },
+        };
+      },
+    ),
+  };
+});
+
+vi.mock("@homarr/redis", () => ({
+  createQueryCacheChannel: redisMock.createQueryCacheChannel,
+}));
+
+vi.mock("@homarr/auth", () => ({ auth: () => ({}) as Session }));
+
+afterEach(() => {
+  vi.useRealTimers();
+  redisMock.values.clear();
+  redisMock.calls.length = 0;
+  redisMock.createQueryCacheChannel.mockClear();
+});
+
+const createSession = (userId = createId()): Session => ({
+  user: {
+    id: userId,
+    permissions: [],
+    colorScheme: "light",
+  },
+  expires: new Date().toISOString(),
+});
+
+const insertUserAsync = async (db: Database, id: string) => {
+  await db.insert(users).values({ id });
+};
+
+describe("isPersistableWidgetQueryKey", () => {
+  test.each([
+    [[["widget", "calendar", "findAllEvents"], { type: "query" }], true],
+    [[["app", "byId"], { type: "query" }], true],
+    [[["app", "byIds"], { type: "query" }], true],
+    [[["docker", "getContainers"], { type: "query" }], true],
+    [[["integration", "byIds"], { type: "query" }], true],
+    [[["widget", "app", "ping"], { type: "query", input: { id: "abc" } }], false],
+    [[["app", "selectable"], { type: "query" }], false],
+    [[["board", "getBoardByName"], { type: "query" }], false],
+    [["widget"], false],
+  ])("matches persist filter for %j", (queryKey, expected) => {
+    expect(isPersistableWidgetQueryKey(queryKey)).toBe(expected);
+  });
+});
+
+describe("queryCacheRouter", () => {
+  test("stores, reads, and removes data for a board viewer", async () => {
+    const db = createDb();
+    const session = createSession();
+    await insertUserAsync(db, session.user.id);
+    await db.insert(boards).values({ id: "board-1", name: "board", creatorId: session.user.id, isPublic: false });
+
+    const caller = queryCacheRouter.createCaller({ db, deviceType: undefined, session });
+
+    await expect(caller.setItem({ boardId: "board-1", key: "query-key", value: "cached-value" })).resolves.toEqual({
+      stored: true,
+    });
+    await expect(caller.getItem({ boardId: "board-1", key: "query-key" })).resolves.toBe("cached-value");
+
+    await caller.removeItem({ boardId: "board-1", key: "query-key" });
+
+    await expect(caller.getItem({ boardId: "board-1", key: "query-key" })).resolves.toBeNull();
+  });
+
+  test("does not touch Redis when board access is denied", async () => {
+    const db = createDb();
+    await insertUserAsync(db, "owner");
+    await db.insert(boards).values({ id: "board-1", name: "board", creatorId: "owner", isPublic: false });
+
+    redisMock.createQueryCacheChannel.mockClear();
+    const caller = queryCacheRouter.createCaller({ db, deviceType: undefined, session: createSession("other-user") });
+
+    await expect(caller.getItem({ boardId: "board-1", key: "query-key" })).rejects.toThrow("Board not found");
+    expect(redisMock.createQueryCacheChannel).not.toHaveBeenCalled();
+  });
+
+  test("scopes anonymous public-board cache entries by anonymous user and board", async () => {
+    const db = createDb();
+    await insertUserAsync(db, "owner");
+    await db.insert(boards).values({ id: "board-1", name: "board", creatorId: "owner", isPublic: true });
+
+    const caller = queryCacheRouter.createCaller({ db, deviceType: undefined, session: null });
+
+    await caller.setItem({ boardId: "board-1", key: "query-key", value: "cached-value" });
+
+    expect(redisMock.calls.at(-1)).toMatchObject({
+      userId: "anonymous",
+      boardId: "board-1",
+      key: "query-key",
+      ttlMs: queryCacheRetentionMs,
+      maxValueBytes: queryCacheMaxValueBytes,
+    });
+  });
+
+  test("scopes signed-in cache entries by user and rejects oversized values", async () => {
+    const db = createDb();
+    const session = createSession("user-1");
+    await insertUserAsync(db, session.user.id);
+    await db.insert(boards).values({ id: "board-1", name: "board", creatorId: session.user.id, isPublic: false });
+
+    const caller = queryCacheRouter.createCaller({ db, deviceType: undefined, session });
+    const value = "x".repeat(queryCacheMaxValueBytes + 1);
+
+    await expect(caller.setItem({ boardId: "board-1", key: "query-key", value })).resolves.toEqual({
+      stored: false,
+    });
+    expect(redisMock.calls.at(-1)).toMatchObject({
+      userId: "user-1",
+      boardId: "board-1",
+      ttlMs: queryCacheRetentionMs,
+      maxValueBytes: queryCacheMaxValueBytes,
+    });
+  });
+
+  test("expires values through the Redis TTL path", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+
+    const db = createDb();
+    const session = createSession("user-1");
+    await insertUserAsync(db, session.user.id);
+    await db.insert(boards).values({ id: "board-1", name: "board", creatorId: session.user.id, isPublic: false });
+
+    const caller = queryCacheRouter.createCaller({ db, deviceType: undefined, session });
+
+    await caller.setItem({ boardId: "board-1", key: "query-key", value: "cached-value" });
+    await expect(caller.getItem({ boardId: "board-1", key: "query-key" })).resolves.toBe("cached-value");
+
+    await vi.advanceTimersByTimeAsync(queryCacheRetentionMs + 1);
+
+    await expect(caller.getItem({ boardId: "board-1", key: "query-key" })).resolves.toBeNull();
+  });
+});
+
+describe("query cache stale handling", () => {
+  test("uses TanStack Query dataUpdatedAt and staleTime to decide when cached data refetches", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-01-01T00:10:00.000Z"));
+
+    const queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+          staleTime: queryCacheDefaultStaleTimeMs,
+        },
+      },
+    });
+    const queryKey = [["widget", "example"], { input: { integrationIds: ["integration-1"] }, type: "query" }];
+    const queryFn = vi.fn().mockResolvedValue("fresh");
+
+    queryClient.setQueryData(queryKey, "cached", {
+      updatedAt: Date.now() - queryCacheDefaultStaleTimeMs - 1,
+    });
+
+    await expect(
+      queryClient.fetchQuery({
+        queryKey,
+        queryFn,
+      }),
+    ).resolves.toBe("fresh");
+
+    expect(queryFn).toHaveBeenCalledOnce();
+  });
+});

packages/boards/src/context.tsx

@@ -6,6 +6,7 @@ import { usePathname } from "next/navigation";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
+import { getActiveQueryCacheBoardId, setActiveQueryCacheBoardId } from "@homarr/api/query-cache";
 
 import { updateBoardName } from "./updater";
 
@@ -28,6 +29,8 @@ export const BoardProvider = ({
     },
   );
 
+  setActiveQueryCacheBoardId(data.id);
+
   // Update the board name so it can be used within updateBoard method
   updateBoardName(initialBoard.name);
 
@@ -42,6 +45,16 @@ export const BoardProvider = ({
     };
   }, [pathname, utils, initialBoard.name]);
 
+  useEffect(() => {
+    setActiveQueryCacheBoardId(data.id);
+
+    return () => {
+      if (getActiveQueryCacheBoardId() === data.id) {
+        setActiveQueryCacheBoardId(null);
+      }
+    };
+  }, [data.id]);
+
   return (
     <BoardContext.Provider
       value={{
@@ -73,7 +86,7 @@ export const getCurrentLayout = (board: RouterOutputs["board"]["getBoardByName"]
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
   if (typeof window === "undefined") return board.layouts.at(0)!.id;
 
-  const sortedLayouts = board.layouts.sort((layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint);
+  const sortedLayouts = board.layouts.toSorted((layoutA, layoutB) => layoutB.breakpoint - layoutA.breakpoint);
 
   // Fallback to smallest if none exists with breakpoint smaller than window width
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion

packages/common/src/url.ts

@@ -1,7 +1,11 @@
 import type { ReadonlyHeaders } from "next/dist/server/web/spec-extension/adapters/headers";
 
 export const removeTrailingSlash = (path: string) => {
-  return path.at(-1) === "/" ? path.substring(0, path.length - 1) : path;
+  let end = path.length;
+  while (end > 0 && path.charAt(end - 1) === "/") {
+    end--;
+  }
+  return path.slice(0, end);
 };
 
 export const extractBaseUrlFromHeaders = (

packages/db/migrations/mysql/0039_add_user_onboarding_tour_status.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `user` ADD `completed_manage_tour` boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE `user` ADD `completed_board_tour` boolean DEFAULT false NOT NULL;

packages/db/migrations/mysql/meta/_journal.json

@@ -274,6 +274,13 @@
       "when": 1775400000000,
       "tag": "0038_add_user_ddg_bangs",
       "breakpoints": true
+    },
+    {
+      "idx": 39,
+      "version": "5",
+      "when": 1779199104477,
+      "tag": "0039_add_user_onboarding_tour_status",
+      "breakpoints": true
     }
   ]
 }

packages/db/migrations/postgresql/0005_add_user_onboarding_tour_status.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "user" ADD COLUMN "completed_manage_tour" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "user" ADD COLUMN "completed_board_tour" boolean DEFAULT false NOT NULL;

packages/db/migrations/postgresql/meta/_journal.json

@@ -36,6 +36,13 @@
       "when": 1775400000000,
       "tag": "0004_add_user_ddg_bangs",
       "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1779199097716,
+      "tag": "0005_add_user_onboarding_tour_status",
+      "breakpoints": true
     }
   ]
 }

packages/db/migrations/seed.ts

@@ -2,6 +2,7 @@ import { createId, objectKeys } from "@homarr/common";
 import {
   createDocumentationLink,
   credentialsAdminGroup,
+  defaultBookmarkApps,
   everyoneGroup,
   getIntegrationDefaultUrl,
   getIntegrationName,
@@ -12,18 +13,20 @@ import { defaultServerSettings, defaultServerSettingsKeys } from "@homarr/server
 
 import type { Database } from "..";
 import { eq } from "..";
-import { getMaxGroupPositionAsync } from "../queries";
+import { getMaxGroupPositionAsync, placeAllWidgetsAsync } from "../queries";
 import {
   getServerSettingByKeyAsync,
   insertServerSettingByKeyAsync,
   updateServerSettingByKeyAsync,
 } from "../queries/server-setting";
 import {
+  apps,
   boards,
   groupMembers,
   groupPermissions,
   groups,
   integrations,
+  items,
   layouts,
   onboarding,
   searchEngines,
@@ -38,6 +41,9 @@ export const seedDataAsync = async (db: Database) => {
   await seedServerSettingsAsync(db);
   await seedDefaultSearchEnginesAsync(db);
   await seedDefaultIntegrationsAsync(db);
+  await seedDefaultAppsAsync(db);
+  await seedDefaultBoardAsync(db);
+  await seedBoardWidgetsAsync(db);
 
   if (process.env.DEMO_MODE === "true") {
     await seedDemoUserAsync(db);
@@ -209,6 +215,64 @@ const seedDefaultIntegrationsAsync = async (db: Database) => {
   console.log(`Created ${createdCount} default integrations through seeding process`);
 };
 
+const seedDefaultAppsAsync = async (db: Database) => {
+  const existingApps = await db.$count(apps);
+  if (existingApps > 0) {
+    console.log("Skipping seeding of default apps as some already exist");
+    return;
+  }
+
+  for (const app of defaultBookmarkApps) {
+    await db.insert(apps).values({
+      id: createId(),
+      name: app.name,
+      iconUrl: app.iconUrl,
+      href: app.href,
+    });
+  }
+  console.log(`Created ${defaultBookmarkApps.length} default apps through seeding process`);
+};
+
+const seedDefaultBoardAsync = async (db: Database) => {
+  const existingBoard = await db.query.boards.findFirst();
+
+  if (existingBoard) {
+    console.log("Skipping seeding of default board as one already exists");
+    return;
+  }
+
+  const boardId = createId();
+  await db.insert(boards).values({
+    id: boardId,
+    name: "dashboard",
+    isPublic: false,
+  });
+  await db.insert(sections).values({
+    id: createId(),
+    kind: "empty",
+    xOffset: 0,
+    yOffset: 0,
+    boardId,
+  });
+  await db.insert(layouts).values({
+    id: createId(),
+    name: "Base",
+    columnCount: 10,
+    breakpoint: 0,
+    boardId,
+  });
+
+  const everyoneGroupRow = await db.query.groups.findFirst({
+    where: eq(groups.name, everyoneGroup),
+  });
+  if (everyoneGroupRow) {
+    await db.update(groups).set({ homeBoardId: boardId }).where(eq(groups.id, everyoneGroupRow.id));
+    console.log("Set default board as home board for everyone group");
+  }
+
+  console.log("Created default board 'dashboard' through seed");
+};
+
 const seedDemoUserAsync = async (db: Database) => {
   const existingUser = await db.query.users.findFirst({
     where: eq(users.name, "demo"),
@@ -250,30 +314,41 @@ const seedDemoUserAsync = async (db: Database) => {
     previousStep: "settings",
   });
 
-  const boardId = createId();
-  await db.insert(boards).values({
-    id: boardId,
-    name: "default",
-    isPublic: false,
-    creatorId: userId,
-  });
-  await db.insert(sections).values({
-    id: createId(),
-    kind: "empty",
-    xOffset: 0,
-    yOffset: 0,
-    boardId,
-  });
-  await db.insert(layouts).values({
-    id: createId(),
-    name: "Base",
-    columnCount: 12,
-    breakpoint: 0,
-    boardId,
-  });
-  await db.update(users).set({ homeBoardId: boardId }).where(eq(users.id, userId));
+  const board = await db.query.boards.findFirst();
+  if (board) {
+    await db.update(users).set({ homeBoardId: board.id }).where(eq(users.id, userId));
+  }
 
   console.log(
     "Your instance has enabled demo mode. Homarr therefore created example data for your demo. You can disable demo mode anytime by setting the env 'DEMO_MODE' to 'false' or unset it.",
   );
 };
+
+const seedBoardWidgetsAsync = async (db: Database) => {
+  const existingItems = await db.$count(items);
+  if (existingItems > 0) {
+    console.log("Skipping seeding of board widgets as some already exist");
+    return;
+  }
+
+  const board = await db.query.boards.findFirst({
+    with: { sections: true, layouts: true },
+  });
+  if (!board) return;
+
+  const section = board.sections.find((sec) => sec.kind === "empty");
+  const layout = board.layouts[0];
+  if (!section || !layout) return;
+
+  const allIntegrations = await db.query.integrations.findMany();
+  const allApps = await db.query.apps.findMany();
+
+  const count = await placeAllWidgetsAsync(
+    db,
+    { boardId: board.id, sectionId: section.id, layoutId: layout.id, columnCount: layout.columnCount },
+    allIntegrations,
+    allApps,
+  );
+
+  console.log(`Placed ${count} widgets on board`);
+};

packages/db/migrations/sqlite/0037_add_user_onboarding_tour_status.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `user` ADD `completed_manage_tour` integer DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE `user` ADD `completed_board_tour` integer DEFAULT false NOT NULL;

packages/db/migrations/sqlite/meta/_journal.json

@@ -260,6 +260,13 @@
       "when": 1775400000000,
       "tag": "0036_add_user_ddg_bangs",
       "breakpoints": true
+    },
+    {
+      "idx": 37,
+      "version": "6",
+      "when": 1779199046805,
+      "tag": "0037_add_user_onboarding_tour_status",
+      "breakpoints": true
     }
   ]
 }

packages/db/queries/index.ts

@@ -1,3 +1,4 @@
 export * from "./item";
 export * from "./server-setting";
 export * from "./group";
+export * from "./widget-placement";

packages/db/queries/widget-placement.ts

@@ -0,0 +1,148 @@
+import superjson from "superjson";
+
+import { createId } from "@homarr/common";
+import {
+  defaultBookmarkApps,
+  defaultWidgetConfigs,
+  emptySuperJSON,
+  getWidgetKindsForIntegration,
+} from "@homarr/definitions";
+import type { WidgetKind } from "@homarr/definitions";
+
+import type { Database } from "..";
+import { integrationItems, itemLayouts, items } from "../schema";
+import type { Integration } from "../schema";
+
+const widgetConfigMap = new Map(defaultWidgetConfigs.map((config) => [config.kind, config]));
+
+interface BoardTarget {
+  boardId: string;
+  sectionId: string;
+  layoutId: string;
+  columnCount: number;
+}
+
+interface PlacementContext extends BoardTarget {
+  xOffset: number;
+  yOffset: number;
+  rowMaxHeight: number;
+}
+
+const placeWidgetAsync = async (
+  db: Database,
+  ctx: PlacementContext,
+  kind: WidgetKind,
+  linkedIntegrationIds: string[],
+  options?: string,
+  size?: { width: number; height: number },
+) => {
+  const itemWidth = size?.width ?? 2;
+  const itemHeight = size?.height ?? 2;
+
+  if (ctx.xOffset + itemWidth > ctx.columnCount) {
+    ctx.xOffset = 0;
+    ctx.yOffset += ctx.rowMaxHeight;
+    ctx.rowMaxHeight = 0;
+  }
+
+  const itemId = createId();
+  await db.insert(items).values({
+    id: itemId,
+    boardId: ctx.boardId,
+    kind,
+    options: options ?? emptySuperJSON,
+    advancedOptions: emptySuperJSON,
+  });
+
+  await db.insert(itemLayouts).values({
+    itemId,
+    sectionId: ctx.sectionId,
+    layoutId: ctx.layoutId,
+    xOffset: ctx.xOffset,
+    yOffset: ctx.yOffset,
+    width: itemWidth,
+    height: itemHeight,
+  });
+
+  for (const integrationId of linkedIntegrationIds) {
+    await db.insert(integrationItems).values({ itemId, integrationId });
+  }
+
+  ctx.rowMaxHeight = Math.max(ctx.rowMaxHeight, itemHeight);
+  ctx.xOffset += itemWidth;
+};
+
+interface App {
+  id: string;
+  name: string;
+}
+
+export const placeAllWidgetsAsync = async (
+  db: Database,
+  target: BoardTarget,
+  allIntegrations: Integration[],
+  allApps: App[],
+) => {
+  const ctx: PlacementContext = {
+    ...target,
+    xOffset: 0,
+    yOffset: 0,
+    rowMaxHeight: 0,
+  };
+
+  const placedWidgets = new Set<WidgetKind>();
+
+  for (const integration of allIntegrations) {
+    for (const widgetKind of getWidgetKindsForIntegration(integration.kind)) {
+      if (placedWidgets.has(widgetKind)) continue;
+      const config = widgetConfigMap.get(widgetKind);
+      if (config?.skip) continue;
+      placedWidgets.add(widgetKind);
+
+      const matchingIds = allIntegrations
+        .filter((row) => getWidgetKindsForIntegration(row.kind).includes(widgetKind))
+        .map((row) => row.id);
+
+      const options = config?.options ? superjson.stringify(config.options) : undefined;
+      await placeWidgetAsync(
+        db,
+        ctx,
+        widgetKind,
+        matchingIds,
+        options,
+        config && { width: config.width, height: config.height },
+      );
+    }
+  }
+
+  for (const app of allApps) {
+    await placeWidgetAsync(
+      db,
+      ctx,
+      "app",
+      [],
+      superjson.stringify({ appId: app.id, openInNewTab: true, showTitle: true }),
+      { width: 1, height: 1 },
+    );
+  }
+
+  const bookmarkAppNames = new Set(defaultBookmarkApps.map((bookmark) => bookmark.name));
+  const bookmarkAppIds = allApps.filter((app) => bookmarkAppNames.has(app.name)).map((app) => app.id);
+
+  for (const config of defaultWidgetConfigs) {
+    if (config.skip || placedWidgets.has(config.kind)) continue;
+    placedWidgets.add(config.kind);
+
+    let options = config.options ? { ...config.options } : undefined;
+    if (config.kind === "bookmarks" && bookmarkAppIds.length > 0) {
+      options = { ...options, items: bookmarkAppIds };
+    }
+
+    await placeWidgetAsync(db, ctx, config.kind, [], options ? superjson.stringify(options) : undefined, {
+      width: config.width,
+      height: config.height,
+    });
+  }
+
+  return placedWidgets.size + allApps.length;
+};

packages/db/schema/mysql.ts

@@ -80,6 +80,8 @@ export const users = mysqlTable("user", {
   colorScheme: varchar({ length: 5 }).$type<ColorScheme>().default("dark").notNull(),
   firstDayOfWeek: tinyint().$type<DayOfWeek>().default(1).notNull(), // Defaults to Monday
   pingIconsEnabled: boolean().default(false).notNull(),
+  completedManageTour: boolean().default(false).notNull(),
+  completedBoardTour: boolean().default(false).notNull(),
 });
 
 export const accounts = mysqlTable(

packages/db/schema/postgresql.ts

@@ -79,6 +79,8 @@ export const users = pgTable("user", {
   colorScheme: varchar({ length: 5 }).$type<ColorScheme>().default("dark").notNull(),
   firstDayOfWeek: smallint().$type<DayOfWeek>().default(1).notNull(), // Defaults to Monday
   pingIconsEnabled: boolean().default(false).notNull(),
+  completedManageTour: boolean().default(false).notNull(),
+  completedBoardTour: boolean().default(false).notNull(),
 });
 
 export const accounts = pgTable(

packages/db/schema/sqlite.ts

@@ -62,6 +62,8 @@ export const users = sqliteTable("user", {
   colorScheme: text().$type<ColorScheme>().default("dark").notNull(),
   firstDayOfWeek: int().$type<DayOfWeek>().default(1).notNull(), // Defaults to Monday
   pingIconsEnabled: int({ mode: "boolean" }).default(false).notNull(),
+  completedManageTour: int({ mode: "boolean" }).default(false).notNull(),
+  completedBoardTour: int({ mode: "boolean" }).default(false).notNull(),
 });
 
 export const accounts = sqliteTable(

packages/definitions/src/docker-integration-match.ts

@@ -0,0 +1,90 @@
+import { objectKeys } from "@homarr/common";
+
+import { integrationDefs } from "./integration";
+import type { IntegrationKind } from "./integration";
+
+export const extractContainerImageName = (image: string): string => image.split("/").at(-1)?.split(":").at(0) ?? "";
+
+const extractIconSlug = (iconUrl: string): string => {
+  const filename = iconUrl.split("/").pop() ?? "";
+  return filename.replace(/\.(svg|png)$/, "").toLowerCase();
+};
+
+export const integrationIconSlugs: Record<IntegrationKind, string> = Object.fromEntries(
+  objectKeys(integrationDefs).map((kind) => [kind, extractIconSlug(integrationDefs[kind].iconUrl)]),
+) as Record<IntegrationKind, string>;
+
+const integrationAliases: Partial<Record<IntegrationKind, readonly string[]>> = {
+  piHole: ["pihole", "pi-hole"],
+  adGuardHome: ["adguardhome", "adguard-home", "adguard"],
+  homeAssistant: ["homeassistant", "home-assistant", "hass"],
+  openmediavault: ["omv"],
+  qBittorrent: ["qbittorrent"],
+  sabNzbd: ["sabnzbd"],
+  nzbGet: ["nzbget"],
+  unifiController: ["unifi", "unifi-controller"],
+  jellyseerr: ["jellyseerr"],
+  overseerr: ["overseerr"],
+  dashDot: ["dashdot", "dash-dot", "dash."],
+  speedtestTracker: ["speedtest-tracker"],
+  searchCh: ["search-ch"],
+  gitHubContainerRegistry: ["ghcr"],
+  linuxServerIO: ["linuxserver"],
+  coolify: ["coolify"],
+  truenas: ["truenas"],
+};
+
+export const matchIntegrationKind = (search: string): IntegrationKind | null => {
+  const normalized = search.toLowerCase().trim();
+  if (!normalized) return null;
+
+  for (const kind of objectKeys(integrationDefs)) {
+    if (kind.toLowerCase() === normalized) return kind;
+    if (integrationDefs[kind].name.toLowerCase() === normalized) return kind;
+  }
+
+  for (const kind of objectKeys(integrationDefs)) {
+    if (integrationIconSlugs[kind] === normalized) return kind;
+  }
+
+  for (const [kind, aliases] of Object.entries(integrationAliases) as [IntegrationKind, readonly string[]][]) {
+    if (aliases.some((alias) => alias === normalized)) return kind;
+  }
+
+  for (const kind of objectKeys(integrationDefs)) {
+    if (normalized.includes(kind.toLowerCase())) return kind;
+    if (normalized.includes(integrationIconSlugs[kind])) return kind;
+  }
+
+  return null;
+};
+
+const notDockerDiscoverable = new Set<IntegrationKind>([
+  "dockerHub",
+  "github",
+  "gitlab",
+  "npm",
+  "codeberg",
+  "linuxServerIO",
+  "gitHubContainerRegistry",
+  "quay",
+  "ical",
+  "searchCh",
+  "mock",
+]);
+
+interface ContainerMatchInput {
+  image: string;
+  name: string;
+}
+
+export const matchIntegrationKindFromContainer = (container: ContainerMatchInput): IntegrationKind | null => {
+  const imageName = extractContainerImageName(container.image);
+  const fromImage = matchIntegrationKind(imageName);
+  if (fromImage && !notDockerDiscoverable.has(fromImage)) return fromImage;
+
+  const fromName = matchIntegrationKind(container.name);
+  if (fromName && !notDockerDiscoverable.has(fromName)) return fromName;
+
+  return null;
+};

packages/definitions/src/index.ts

@@ -12,5 +12,8 @@ export * from "./docs";
 export * from "./cookie";
 export * from "./search-engine";
 export * from "./onboarding";
+export * from "./widget-integration-map";
 export * from "./emptysuperjson";
 export * from "./hotkeys";
+export * from "./docker-integration-match";
+export * from "./integration-url-template";