docs: add visual catalog and screenshots for all dashboard surfaces and widgets

Add full visual catalog in SCREENSHOTS.md with corresponding captured screenshots
for all Homarr core dashboard surfaces, administration modules, and all 55 widget
interfaces (preview, edit mode, settings, advanced settings, and dimensions).

Co-authored-by: Cursor <cursoragent@cursor.com>

.agents/skills/codebase-context/SKILL.md

@@ -1,40 +1,195 @@
 ---
 name: codebase-context
-description: Navigate Homarr's monorepo architecture and reuse shared packages. Use when locating code, choosing a package boundary, understanding runtime services, tRPC, databases, widgets, integrations, cron jobs, Custom Widgets, Workshop, or checking @homarr/common before creating a utility.
+description: Comprehensive Homarr codebase architecture and conventions reference. Use when orienting in the monorepo, understanding package dependency layers, the three runtime services and ports, tRPC router structure, multi-database support, widget/integration/cron system architecture, routing, auth providers, env vars, or key patterns before writing code.
 ---
 
 # Homarr Codebase Context
 
-Orient from the current checkout before editing. Treat package manifests, exports, and source as authoritative when they differ from this snapshot.
+Homarr is an open-source, self-hosted dashboard for managing homelab services. It integrates with 50+ self-hosted apps (media servers, download clients, DNS, NAS, etc.) and provides a drag-and-drop widget-based UI.
 
-## Workflow
+## Tech Stack
 
-1. Confirm the branch and inspect the nearest `package.json`, existing sibling modules, and package exports.
-2. Search `@homarr/common` before creating a general-purpose helper. Read [references/common.md](references/common.md) for every public entrypoint and export.
-3. Read [references/architecture.md](references/architecture.md) when the task crosses packages, runtimes, routing, data, widgets, integrations, cron jobs, Custom Widgets, or Workshop.
-4. Keep the change in the deepest package that owns the behavior. Reuse public entrypoints rather than deep-importing implementation files.
-5. Re-run targeted searches before documenting counts, consumers, or dependency edges; these change faster than the architectural seams.
+- **Monorepo**: pnpm workspaces + Turborepo
+- **Framework**: Next.js (App Router, `output: "standalone"`) — T3 Stack
+- **Language**: TypeScript throughout
+- **ORM**: Drizzle (supports SQLite via better-sqlite3, MySQL, PostgreSQL)
+- **API**: tRPC (HTTP + WebSocket subscriptions) with superjson + OpenAPI bridge via `trpc-to-openapi`
+- **Auth**: NextAuth v5 (database sessions, Credentials/LDAP/OIDC providers)
+- **UI**: Mantine v9 (not Tailwind) + Tabler icons
+- **State**: Jotai (atoms), TanStack Query (server state via tRPC)
+- **Realtime**: WebSocket server (`ws`) for tRPC subscriptions, backed by Redis pub/sub
+- **Cron**: `node-cron` in a standalone Fastify service (`apps/tasks`)
+- **i18n**: next-intl with `[locale]` dynamic segment (prefix mode: `"never"`, locale from cookie)
+- **Testing**: Vitest + jsdom, Playwright for E2E
+- **Lint/Format**: oxlint + oxfmt (not ESLint/Prettier)
+- **Docs**: Docusaurus 3 in `apps/docs/` (`@homarr/docs`)
+- **Package manager**: pnpm 10.34.1, Node >= 24.16.0
 
-## Current toolchain
+## Repository Structure
 
-- Use Node `24.18.0` from `mise.toml` and pnpm `11.15.1` from `package.json`.
-- Use pnpm workspaces with Turborepo. Workspace packages use the `@homarr/` scope and catalog-managed dependencies.
-- Use Next.js App Router, TypeScript, tRPC, Drizzle, Mantine v9, Tabler icons, Jotai, TanStack Query, next-intl, Vitest, and Playwright.
-- Use oxlint and oxfmt. Mantine is the application UI system; Tailwind is limited to the docs app.
-- `pnpm dev` starts only `@homarr/nextjs`. Start a standalone runtime explicitly when the task needs it.
+```text
+homarr/
+├── apps/
+│   ├── nextjs/          # Main Next.js application (port 3000)
+│   ├── docs/            # Docusaurus 3 documentation site (@homarr/docs)
+│   ├── tasks/           # Cron job runner + Fastify tRPC API (port 3002)
+│   └── websocket/       # Standalone tRPC WebSocket server (port 3001)
+├── packages/
+│   ├── api/             # tRPC appRouter, procedures, OpenAPI
+│   ├── auth/            # NextAuth config, providers, session, API keys
+│   ├── db/              # Drizzle schema (3 DB drivers), migrations, queries
+│   ├── core/            # Env validation, DB/Redis driver factories, logging
+│   ├── definitions/     # Domain enums: WidgetKind, IntegrationKind, permissions
+│   ├── widgets/         # All 39 dashboard widgets (definitions + components)
+│   ├── integrations/    # Integration classes (HTTP clients to external apps)
+│   ├── redis/           # Redis pub/sub channels, caching abstractions
+│   ├── translation/     # next-intl setup, locale configs, lang JSON files
+│   ├── ui/              # Shared Mantine components, theme, hooks
+│   ├── validation/      # Shared zod schemas for API/forms
+│   ├── common/          # Shared utilities, IDs, errors
+│   ├── cron-jobs/       # Cron job implementations (25+ jobs)
+│   ├── cron-jobs-core/  # Cron scheduling primitives
+│   ├── cron-job-api/    # tRPC router for job management (start/stop/trigger)
+│   ├── cron-job-status/ # Cron status via Redis
+│   ├── boards/          # Board context, edit mode, cache updater
+│   ├── modals/          # Modal primitives on Mantine
+│   ├── modals-collection/ # Feature modals (apps, boards, docker, etc.)
+│   ├── form/            # useZodForm (Mantine + zod resolver)
+│   ├── forms-collection/# Reusable form UIs (new app, icon picker, upload)
+│   ├── spotlight/       # Command palette / search with multiple modes
+│   ├── request-handler/ # Server request handlers (feeds, integrations)
+│   ├── notifications/   # Mantine notifications wrapper
+│   ├── docker/          # Dockerode-based Docker access
+│   ├── icons/           # Icon DB/repo integration
+│   ├── image-proxy/     # Image proxy + caching
+│   ├── ping/            # Reachability / ping utilities
+│   ├── analytics/       # Server-side analytics (Umami)
+│   ├── server-settings/ # Server setting keys/types
+│   ├── settings/        # User-facing settings UI context
+│   └── cli/             # Node CLI for ops (brocli)
+├── tooling/
+│   ├── typescript/      # Base tsconfig
+│   └── github/          # CI setup action
+├── development/         # Dev docker-compose (Redis, MySQL, PostgreSQL)
+├── e2e/                 # E2E test specs
+└── Dockerfile           # Multi-stage production build
+```
 
-## High-value seams
+## Three Runtime Services
 
-- Server/RSC tRPC: `@homarr/api/server`
-- Client tRPC hooks: `@homarr/api/client`
-- Main router: `packages/api/src/root.ts`
-- MCP eager router: `packages/api/src/mcp.ts`
-- Database schemas: `packages/db/schema/{sqlite,mysql,postgresql}.ts`
-- Widget registry: `packages/widgets/src/registry.ts`
-- Widget loading manifest: `packages/widgets/src/manifest.ts`
-- Integration definitions: `packages/definitions/src/integration.ts`
-- Integration factory: `packages/integrations/src/base/creator.ts`
-- Cron jobs: `packages/cron-jobs/src/jobs/`
-- App routes: `apps/nextjs/src/app/[locale]/`
+| Service   | Port | Role                                         |
+| --------- | ---- | -------------------------------------------- |
+| Next.js   | 3000 | Main web app (SSR + API routes)              |
+| WebSocket | 3001 | tRPC subscriptions via `ws`                  |
+| Tasks     | 3002 | Cron job runner + management API via Fastify |
 
-When a code change affects users, invoke `documentation-sync`. When exposing tRPC through MCP, invoke `mcp-integration`.
+In Docker, nginx listens on **7575** and proxies to all three. The tasks service authenticates via `CRON_JOB_API_KEY` header.
+
+## Package Dependency Layers
+
+1. **Foundation**: `core` (env, DB drivers, Redis client, logging) → no `@homarr` deps
+2. **Domain**: `definitions` → `common` → `core`
+3. **Data**: `db` → `core`, `definitions`, `common`
+4. **Auth**: `auth` → `db`, `definitions`, `core`, `validation`
+5. **Cross-cutting**: `translation`, `validation`, `redis`, `server-settings`
+6. **Feature backends**: `integrations`, `request-handler`, `cron-jobs`, `docker`, `ping`
+7. **API surface**: `api` → pulls in auth, db, redis, integrations, etc.
+8. **UI stack**: `ui`, `modals`, `form`, `notifications`, `boards`, `spotlight`
+9. **Composed features**: `widgets`, `modals-collection`, `forms-collection`
+
+## Key Patterns
+
+### tRPC
+
+- **Server caller** (RSC): `import { api } from "@homarr/api/server"` → cached caller with auth context
+- **Client hooks**: `import { clientApi } from "@homarr/api/client"` → React Query hooks
+- **Router structure**: `packages/api/src/root.ts` defines top-level namespaces (`user`, `board`, `widget`, `integration`, `docker`, `kubernetes`, etc.)
+- **Procedures**: `publicProcedure`, `protectedProcedure`, `permissionRequiredProcedure`, `onboardingProcedure`
+- **WebSocket subscriptions**: Client uses `wsLink` when `type === "subscription"`, connects to port 3001
+
+### Multi-Database Support
+
+Drizzle schemas exist in three parallel implementations:
+
+- `packages/db/schema/sqlite.ts`
+- `packages/db/schema/mysql.ts`
+- `packages/db/schema/postgresql.ts`
+
+Selected at runtime via `DB_DRIVER` env (`better-sqlite3` | `mysql2` | `node-postgres`). Migrations are per-engine in `packages/db/migrations/{sqlite,mysql,postgresql}/`.
+
+### Widget System
+
+Widgets are registered in `packages/widgets/src/index.tsx` as `widgetImports` (must satisfy `Record<WidgetKind, ...>`). Each widget:
+
+- Has a `definition` created via `createWidgetDefinition(kind, { icon, createOptions, supportedIntegrations? })`
+- Uses `optionsBuilder.from(factory => ({ ... }))` for typed options
+- Loads dynamically via `next/dynamic`
+- Fetches data via tRPC client hooks (backed by cron job caches)
+
+### Integration System
+
+Integrations are defined in `packages/definitions/src/integration.ts` (`integrationDefs`) and instantiated via `createIntegrationAsync` in `packages/integrations/src/base/creator.ts`. Each extends abstract `Integration` class with `testConnectionAsync` and typed methods.
+
+### Cron Job System
+
+Jobs defined in `packages/cron-jobs/src/jobs/`. Each job:
+
+- Uses `createCronJob` with a cron expression
+- Publishes results to Redis channels
+- Widget subscriptions consume those channels via tRPC subscriptions
+- Job management (start/stop/trigger) via `cronJobApi` HTTP client to port 3002
+
+### Modals
+
+Created with `createModal(component).withOptions({ defaultTitle })` from `@homarr/modals`. Opened via `useModalAction(SomeModal)`. Feature modals live in `packages/modals-collection/`.
+
+### Forms
+
+`useZodForm` from `@homarr/form` wraps Mantine `useForm` with zod validation. Shared form UIs in `packages/forms-collection/`.
+
+### Routing (App Router)
+
+- `apps/nextjs/src/app/[locale]/` — all UI routes under locale segment
+- Route groups: `(home)`, `(content)`, `(board)` — don't affect URLs
+- Key routes: `boards/[name]`, `manage/...` (admin), `auth/login`, `init` (onboarding), `widgets/[kind]`
+- Locale driven by cookie (no URL prefix)
+
+### Auth Providers
+
+Configured via `AUTH_PROVIDERS` env. Supports: `credentials` (local), `ldap`, `oidc`. Database sessions with httpOnly cookies. API key auth for programmatic access.
+
+## Environment Variables
+
+Key env vars (from `.env.example`):
+
+- `DB_DRIVER`: `better-sqlite3` | `mysql2` | `node-postgres`
+- `DB_URL`: Database connection string
+- `AUTH_SECRET`: NextAuth secret
+- `SECRET_ENCRYPTION_KEY`: AES-256-CBC for integration secrets
+- `AUTH_PROVIDERS`: Comma-separated (`credentials`, `ldap`, `oidc`)
+- `CRON_JOB_API_KEY`: Shared key between Next.js and tasks service
+- `REDIS_*`: Redis connection (host, port, password)
+- `ENABLE_KUBERNETES`: Optional Kubernetes integration
+
+## Development Commands
+
+- `pnpm dev` — runs all three services in parallel via Turborepo
+- `pnpm docker:dev` — starts Redis + MySQL + PostgreSQL containers
+- `pnpm db:push` — push schema to SQLite (dev)
+- `pnpm db:studio` — Drizzle Studio
+- `pnpm test` — Vitest unit tests
+- `pnpm test:e2e` — Playwright E2E
+- `pnpm lint` / `pnpm format` — oxlint + oxfmt
+- `pnpm dev:docs` — Docusaurus docs site (port 3003)
+- `pnpm typecheck` — tsc --noEmit across all packages
+
+## Conventions
+
+- Workspace packages use `@homarr/` scope
+- All versions managed via pnpm `catalog:` in workspace
+- Path alias `~/*` → `./src/*` in Next.js app
+- Mantine for all UI (no Tailwind) — primary color is red, `autoContrast: true`
+- Icons from `@tabler/icons-react`
+- Drag-and-drop via `@dnd-kit/*`
+- `typescript.ignoreBuildErrors: true` in next.config (types checked separately via `typecheck`)
+- `serverExternalPackages`: `dockerode`, `isomorphic-dompurify`, `jsdom`

.agents/skills/codebase-context/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Homarr Codebase Context"
-  short_description: "Navigate Homarr architecture and shared APIs"
-  default_prompt: "Use $codebase-context to locate the right Homarr package and reuse existing shared APIs."

.agents/skills/codebase-context/references/architecture.md

@@ -1,110 +0,0 @@
-# Homarr architecture
-
-## Contents
-
-- [Applications and runtimes](#applications-and-runtimes)
-- [Package map](#package-map)
-- [Dependency direction](#dependency-direction)
-- [Core patterns](#core-patterns)
-- [Commands and conventions](#commands-and-conventions)
-
-## Applications and runtimes
-
-| Path             | Role                                                                                     |
-| ---------------- | ---------------------------------------------------------------------------------------- |
-| `apps/nextjs`    | Main Next.js application and HTTP APIs on port 3000                                      |
-| `apps/docs`      | Docusaurus documentation site on port 3003                                               |
-| `apps/tasks`     | Cron-job initialization and scheduling runtime; it does not expose the old port-3002 API |
-| `apps/websocket` | tRPC WebSocket subscriptions on port 3001                                                |
-| `apps/workshop`  | Go/PocketBase Workshop service and provider integration                                  |
-
-`pnpm dev` runs only `@homarr/nextjs`. Use `pnpm --filter @homarr/tasks dev`, `pnpm --filter @homarr/websocket dev`, or `pnpm dev:docs` when a task needs those runtimes.
-
-In production, `apps/nextjs/src/instrumentation-node.ts` starts the tasks and WebSocket runtimes inside the Node process. Nginx listens on port 7575, proxies `/websockets` to port 3001, and sends other traffic to port 3000. Redis can run internally or externally.
-
-## Package map
-
-### Foundation and domain
-
-- `core`: environment validation, database and Redis factories, logging, infrastructure.
-- `definitions`: domain enums, integration definitions, widget kinds, permissions.
-- `common`: shared utilities with environment-specific entrypoints. Search it before adding helpers.
-- `validation`: shared Zod schemas.
-- `server-settings`: typed server-setting keys and access.
-
-### Data, identity, and transport
-
-- `db`: Drizzle schemas, queries, migrations, and three database drivers.
-- `auth`: Auth.js/NextAuth configuration, sessions, providers, and API keys.
-- `api`: tRPC routers, contexts, MCP metadata extraction, OpenAPI, and client/server entrypoints.
-- `redis`: Redis clients, pub/sub channels, and caches.
-- `cron-jobs-core`, `cron-jobs`, `cron-job-status`: scheduling primitives, job implementations, and status transport.
-
-### Backends and external systems
-
-- `integrations`: typed clients for external applications.
-- `request-handler`: shared server request flows.
-- `docker`, `ping`, `image-proxy`, `icons`, `analytics`: bounded infrastructure capabilities.
-- `custom-widgets`: Custom JSX v2 schema, validation, runtime, and security contracts.
-- `workshop`: TypeScript Workshop client, backend contracts, and schemas used by Homarr.
-
-### UI and composed features
-
-- `ui`: shared Mantine components, theme, and hooks. Search here before creating a primitive.
-- `form`, `forms-collection`: Zod-backed form setup and reusable forms.
-- `modals`, `modals-collection`: modal primitives and feature modals.
-- `boards`: board state, edit mode, and cache coordination.
-- `settings`, `spotlight`, `notifications`, `onboarding`: cross-feature UI flows.
-- `widgets`: widget definitions, dynamic component loaders, and shared widget UI.
-- `translation`: next-intl configuration and locale catalogs.
-- `cli`: Node operations CLI. `tools/homarr-dev` is the separate Go developer CLI.
-
-## Dependency direction
-
-Prefer these directions; verify the exact dependency in package manifests before changing a boundary.
-
-1. Put infrastructure in `core` and stable domain names in `definitions`.
-2. Put reusable, dependency-light helpers in `common`; use its public environment-specific entrypoints.
-3. Build persistence in `db`, identity in `auth`, transport in `redis`, and external clients in `integrations`.
-4. Compose server behavior in `api`, `cron-jobs`, and request-handler packages.
-5. Build primitives in `ui`, `form`, and `modals`; compose product surfaces in widgets and collection packages.
-6. Keep app entrypoints in `apps/*` thin. Avoid moving reusable behavior into `apps/nextjs` when a package already owns it.
-
-## Core patterns
-
-### tRPC and MCP
-
-`packages/api/src/root.ts` lazily composes the application router. Server components use `@homarr/api/server`; client components use `@homarr/api/client`. MCP extraction requires the eager router in `packages/api/src/mcp.ts`, so MCP-enabled subrouters must be imported and registered there directly. Use the `mcp-integration` skill for exposure and security rules.
-
-### Databases
-
-Drizzle schemas live in parallel files under `packages/db/schema/`. `DB_DRIVER` selects `better-sqlite3`, `mysql2`, or `node-postgres`; migrations live in matching directories under `packages/db/migrations/`. Apply schema behavior consistently across all supported drivers unless the task is explicitly driver-specific.
-
-### Widgets
-
-`packages/widgets/src/registry.ts` owns the explicit widget-module and component-loader registries. `packages/widgets/src/manifest.ts` caches those loaders and exposes definitions, components, and combined resources. Widget modules use `createWidgetDefinition` and typed option builders. Data commonly comes from tRPC queries or Redis-backed cron results. Use existing shared widget components before creating local variants.
-
-### Integrations
-
-`packages/definitions/src/integration.ts` owns `integrationDefs` and `IntegrationKind`. `packages/integrations/src/base/creator.ts` owns `createIntegrationAsync`; concrete integrations implement the shared base contract. Keep credentials and permission checks on server-owned paths.
-
-### Cron jobs
-
-Jobs live in `packages/cron-jobs/src/jobs/` and use `createCronJob`. `apps/tasks` initializes and starts the job group. Job results and status can flow through Redis and tRPC; the retired port-3002 management-API model is no longer part of the architecture.
-
-### Routing and localization
-
-User routes live below `apps/nextjs/src/app/[locale]/`; the locale segment does not add a URL prefix. Route groups organize home and board surfaces. Administrative routes live under `manage`, Custom Widget configuration has a token route, and Workshop has a management surface.
-
-### Custom Widgets and Workshop
-
-`packages/custom-widgets` owns the Custom JSX v2 contract. `packages/workshop` is the Homarr-side client/contract package; `apps/workshop` is the separate Go/PocketBase service. Use the `homarr-custom-widget` skill for authoring and security constraints.
-
-## Commands and conventions
-
-- Read current scripts from the root or package `package.json`; avoid caching commands that do not exist.
-- Use `pnpm dev` for Next.js, `pnpm dev:docs` for docs, and `pnpm dev:cli -- <args>` for the Go developer CLI.
-- Use `pnpm docker:dev:up` for the Redis development dependency.
-- Use package-filtered typechecks or focused tests for the touched behavior.
-- Use `~/*` only inside the Next.js app. Use public `@homarr/*` entrypoints across package boundaries.
-- Keep Mantine application styles separate from the Tailwind-based docs app.

.agents/skills/codebase-context/references/common.md

@@ -1,86 +0,0 @@
-# `@homarr/common` public API
-
-## Contents
-
-- [Reuse workflow](#reuse-workflow)
-- [Entrypoints](#entrypoints)
-- [Root exports](#root-exports)
-- [Types exports](#types-exports)
-- [Server exports](#server-exports)
-- [Client and environment exports](#client-and-environment-exports)
-
-## Reuse workflow
-
-Before writing a utility, search both the public name and the behavior:
-
-```bash
-rg -n "export (const|function|class|type|interface)|export \*" packages/common
-rg -n "@homarr/common" apps packages
-```
-
-Import only from an exported package entrypoint. Do not deep-import `@homarr/common/src/*`. Check `packages/common/package.json` and the source again when adding or renaming an export; this inventory describes the current repository tree.
-
-## Entrypoints
-
-| Import                  | Source                       | Environment                                                                         |
-| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
-| `@homarr/common`        | `index.ts` -> `src/index.ts` | Shared root; includes React hooks and some Next/Mantine-aware helpers               |
-| `@homarr/common/types`  | `src/types.ts`               | Type-only utilities                                                                 |
-| `@homarr/common/server` | `src/server.ts`              | Node/server-only security, encryption, request, error, and bounded-response helpers |
-| `@homarr/common/client` | `src/client.ts`              | Client-facing Next server action export                                             |
-| `@homarr/common/env`    | `env.ts`                     | Validated package environment                                                       |
-
-## Root exports
-
-| Area              | Public exports                                                                                                                                       | Purpose                                                         |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| Objects           | `objectKeys`, `objectEntries`, `hashObjectBase64`                                                                                                    | Typed key/entry iteration and stable query-key hashing          |
-| Strings           | `capitalize`, `isNullOrWhitespace`, `bestMatch`, `normalizeImageName`, `getImageMatchRank`                                                           | Text normalization and matching                                 |
-| Cookies           | `parseCookies`, `setClientCookie`                                                                                                                    | Cookie parsing and browser cookie serialization                 |
-| Arrays            | `splitToNChunks`, `splitToChunksWithNItems`                                                                                                          | Split by number of groups or maximum group size                 |
-| Dates             | `formatDuration`, `toValidDate`, `isDateWithin`                                                                                                      | Duration formatting, safe date coercion, relative-window checks |
-| Timing            | `Stopwatch`                                                                                                                                          | Elapsed-time measurement and formatting                         |
-| React hooks       | `useTimeAgo`, `useIntegrationConnected`                                                                                                              | Relative time and integration freshness state                   |
-| URLs              | `removeTrailingSlash`, `extractBaseUrlFromHeaders`, `getPortFromUrl`, `isAbsoluteUrl`, `SAFE_NEW_TAB_REL`, `getSafeApplicationUrl`, `getSafeAppHref` | URL normalization, safe navigation, ports, and new-tab policy   |
-| Numbers and bytes | `formatNumber`, `randomInt`, `formatBytes`, `formatBytesPair`, `formatByteRate`, `metricToImperial`, `imperialToMetric`                              | Compact numbers, byte displays, rates, and unit conversion      |
-| Legacy bytes      | `humanFileSize`                                                                                                                                      | Deprecated; use the `formatBytes*` helpers in new code          |
-| Byte types        | `ByteUnitSystem`, `FormatBytesOptions`                                                                                                               | Options for byte formatting                                     |
-| Errors            | `extractErrorMessage`, `FlattenError`                                                                                                                | Unknown-error messages and flattenable domain errors            |
-| Theme             | `getMantineColor`                                                                                                                                    | Resolve a Mantine color and shade                               |
-| Functions         | `isFunction`                                                                                                                                         | Unknown-value function guard                                    |
-| Grid              | `GridAlgorithmItem`, `generateResponsiveGridFor`                                                                                                     | Responsive nested-section grid placement                        |
-| IDs               | `createId`                                                                                                                                           | CUID2 ID creation                                               |
-
-The root deliberately does not re-export `types`, `server`, `client`, or `env`; use their named entrypoints.
-
-## Types exports
-
-`@homarr/common/types` exports:
-
-- `MaybePromise<T>`
-- `AtLeastOneOf<T>`
-- `Modify<T, R>`
-- `RemoveReadonly<T>`
-- `MaybeArray<T>`
-- `Inverse<T>`
-- `inferSearchParamsFromSchema<TSchema>`
-
-## Server exports
-
-`@homarr/common/server` exports:
-
-- Security: `generateSecureRandomToken`.
-- Encryption: `encryptSecret`, `decryptSecret`, `decryptSecretWithKey`, `createKeyedFingerprint`, `verifyKeyedFingerprint`.
-- Requests: `userAgent`, `DeviceType`, `ipAddressFromHeaders`.
-- Bounded bodies: `readBoundedJsonResponseAsync`.
-- Parse errors: `ParseError`, `ParseErrorHandler`, `ZodParseErrorHandler`, `JsonParseErrorHandler`.
-- HTTP handlers: `HttpErrorHandler`, `FetchHttpErrorHandler`, `matchErrorCode`, `OFetchHttpErrorHandler`, `AxiosHttpErrorHandler`, `TsdavHttpErrorHandler`, `OctokitHttpErrorHandler`.
-- HTTP errors: `RequestError`, `ResponseError`, `requestErrorMap`.
-- HTTP error types: `AnyRequestError`, `AnyRequestErrorInput`, `RequestErrorInput`, `RequestErrorType`, `RequestErrorReason`, `AnyRequestErrorReason`, `RequestErrorCode`.
-
-`NodeFetchHttpErrorHandler` exists as an implementation file but is not exported by the public server entrypoint. Add an intentional public export before using it across packages.
-
-## Client and environment exports
-
-- `@homarr/common/client` exports `revalidatePathActionAsync`, a Next server action for page revalidation.
-- `@homarr/common/env` exports `env` with validated `NODE_ENV`, `SECRET_ENCRYPTION_KEY`, and `NO_EXTERNAL_CONNECTION` values.

.agents/skills/datatable-migration/SKILL.md

@@ -0,0 +1,691 @@
+---
+name: datatable-migration
+description: Playbook for migrating tables from mantine-react-table (MRT) to mantine-datatable. Use when converting any table component from mantine-react-table to mantine-datatable, working on DataTable column/sort/expansion/context-menu code, or implementing responsive column visibility, column persistence, or transparent tables in widgets.
+---
+
+# Migrating Tables from mantine-react-table to mantine-datatable
+
+This document captures every pattern, fix, and decision from the downloads widget rework (PR #6430). Use it as a playbook when porting other tables.
+
+## Migration Candidates
+
+Current `mantine-react-table` consumers that could be migrated:
+
+**Widgets (in `packages/widgets/`):**
+
+- `docker/component.tsx` — Docker container table
+- `media-server/component.tsx` — Media server sessions
+
+**Admin pages (in `apps/nextjs/src/app/[locale]/manage/`):**
+
+- `tools/docker/docker-table.tsx`
+- `tools/tasks/_components/tasks-table.tsx`
+- `tools/api/components/api-keys.tsx`
+- `users/_components/user-list.tsx`
+- `users/invites/_components/invite-list.tsx`
+- `tools/kubernetes/` — 8 Kubernetes resource tables
+
+**Modals:**
+
+- `packages/modals-collection/src/search-engines/request-media-modal.tsx`
+
+**Shared hook to remove once all migrated:**
+
+- `packages/ui/src/hooks/use-translated-mantine-react-table.ts`
+
+## 1. Core Migration: mantine-react-table → mantine-datatable
+
+### Import changes
+
+```typescript
+// BEFORE
+import { MantineReactTable, useMantineReactTable } from "mantine-react-table";
+import type { MRT_ColumnDef } from "mantine-react-table";
+
+// AFTER
+import { DataTable, useDataTableColumns } from "mantine-datatable";
+import type { DataTableColumn, DataTableSortStatus } from "mantine-datatable";
+```
+
+### Column definition shape
+
+```typescript
+// BEFORE (MRT)
+const columns: MRT_ColumnDef<MyRow>[] = [
+  {
+    accessorKey: "name",
+    header: "Name",
+    size: 200,
+    enableSorting: true,
+    Cell: ({ row }) => <Text>{row.original.name}</Text>,
+  },
+];
+
+// AFTER (mantine-datatable)
+const columns: DataTableColumn<MyRow>[] = [
+  {
+    accessor: "name",           // not accessorKey
+    title: "Name",              // not header
+    width: 200,                 // not size
+    sortable: true,             // not enableSorting
+    render: (record) => <Text>{record.name}</Text>,  // not Cell
+  },
+];
+```
+
+Key differences:
+
+- `accessorKey` → `accessor`
+- `header` → `title`
+- `size` → `width`
+- `Cell: ({ row }) =>` → `render: (record) =>`
+- `enableSorting` → `sortable`
+- `enableColumnActions` → does not exist (no column action menus)
+- `mantineTableBodyCellProps` → `cellsStyle` in `defaultColumnProps`
+
+### Table component
+
+```typescript
+// BEFORE
+const table = useTranslatedMantineReactTable({ columns, data, ... });
+return <MantineReactTable table={table} />;
+
+// AFTER
+return (
+  <DataTable
+    records={data}
+    columns={columns}
+    sortStatus={sortStatus}
+    onSortStatusChange={setSortStatus}
+    ...
+  />
+);
+```
+
+### Sorting is manual
+
+mantine-datatable does NOT sort for you. You must sort the data yourself:
+
+```typescript
+const [sortStatus, setSortStatus] = useState<DataTableSortStatus<MyRow>>({
+  columnAccessor: "name",
+  direction: "asc",
+});
+
+const sortedData = useMemo(() => {
+  const mult = sortStatus.direction === "desc" ? -1 : 1;
+  return [...data].toSorted((a, b) => {
+    const aVal = a[sortStatus.columnAccessor];
+    const bVal = b[sortStatus.columnAccessor];
+    if (typeof aVal === "string") return aVal.localeCompare(bVal as string) * mult;
+    return ((aVal as number) - (bVal as number)) * mult;
+  });
+}, [data, sortStatus]);
+
+// Pass sortedData to records, not data
+<DataTable records={sortedData} sortStatus={sortStatus} onSortStatusChange={setSortStatus} />
+```
+
+## 2. Making Tables Transparent (Widget Context)
+
+Widgets sit inside board cards that have user-controlled opacity. The table must be fully transparent so the card background shows through. mantine-datatable defaults to `var(--mantine-color-body)` which is opaque.
+
+Create a CSS file alongside the component:
+
+```css
+/* styles.css */
+.my-table,
+.my-table .mantine-datatable-table,
+.my-table .mantine-datatable-table thead,
+.my-table .mantine-datatable-table tbody,
+.my-table .mantine-datatable-table tfoot,
+.my-table th,
+.my-table td {
+  background-color: transparent !important;
+}
+
+.my-table .mantine-datatable-table tr {
+  background-color: transparent;
+}
+
+/* Hover: translucent instead of opaque */
+.my-table .mantine-datatable-table tbody tr:hover {
+  background-color: color-mix(
+    in srgb,
+    var(--mantine-color-default-hover) 40%,
+    transparent
+  ) !important;
+}
+
+/* Headers: frosted glass effect */
+.my-table th {
+  white-space: nowrap;
+  background-color: color-mix(
+    in srgb,
+    var(--mantine-color-body) 60%,
+    transparent
+  ) !important;
+  backdrop-filter: blur(8px);
+}
+
+/* Cell overflow */
+.my-table td {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* Hide sort icon until hover */
+.my-table .mantine-datatable-header-cell-sortable-icon {
+  opacity: 0;
+  transition: opacity 150ms;
+}
+.my-table th:hover .mantine-datatable-header-cell-sortable-icon {
+  opacity: 1;
+}
+
+/* Row expansion area */
+.my-table .mantine-datatable-row-expansion-cell {
+  background-color: color-mix(
+    in srgb,
+    var(--mantine-color-body) 40%,
+    transparent
+  ) !important;
+}
+```
+
+Import it: `import "./styles.css";` and apply via `className="my-table"`.
+
+## 3. Responsive Column Visibility
+
+Use a lookup table of width breakpoints instead of media queries. The widget receives `width` as a prop.
+
+```typescript
+interface SizeConfig {
+  fontSize: "xs" | "sm";
+  iconSize: number;
+  cellPadding: number;
+  showSpeedColumns: boolean;
+  showTimeColumn: boolean;
+  showStateColumn: boolean;
+}
+
+const SIZE_BREAKPOINTS: { maxWidth: number; config: SizeConfig }[] = [
+  {
+    maxWidth: 300,
+    config: {
+      fontSize: "xs",
+      iconSize: 12,
+      cellPadding: 2,
+      showSpeedColumns: false,
+      showTimeColumn: false,
+      showStateColumn: false,
+    },
+  },
+  {
+    maxWidth: 500,
+    config: {
+      fontSize: "xs",
+      iconSize: 14,
+      cellPadding: 4,
+      showSpeedColumns: false,
+      showTimeColumn: true,
+      showStateColumn: false,
+    },
+  },
+];
+
+const DEFAULT_SIZE_CONFIG: SizeConfig = {
+  fontSize: "sm",
+  iconSize: 14,
+  cellPadding: 4,
+  showSpeedColumns: true,
+  showTimeColumn: true,
+  showStateColumn: true,
+};
+
+function getSizeConfig(width: number): SizeConfig {
+  for (const { maxWidth, config } of SIZE_BREAKPOINTS) {
+    if (width < maxWidth) return config;
+  }
+  return DEFAULT_SIZE_CONFIG;
+}
+
+// Usage: memoize it
+const size = useMemo(() => getSizeConfig(width), [width]);
+```
+
+Then use a visibility check lookup table for columns:
+
+```typescript
+const columnVisibilityChecks: Partial<
+  Record<string, (ctx: ColumnContext) => boolean>
+> = {
+  upSpeed: (ctx) => ctx.hasTorrents && ctx.size.showSpeedColumns,
+  downSpeed: (ctx) => ctx.size.showSpeedColumns,
+  time: (ctx) => ctx.size.showTimeColumn,
+  state: (ctx) => ctx.size.showStateColumn,
+};
+
+function shouldIncludeColumn(accessor: string, ctx: ColumnContext): boolean {
+  if (!ctx.optionsColumnSet.has(accessor)) return false;
+  const check = columnVisibilityChecks[accessor];
+  if (check && !check(ctx)) return false;
+  return true;
+}
+```
+
+## 4. Column Persistence (Drag/Resize → Server)
+
+`useDataTableColumns` stores column order and widths in localStorage by default. For widgets, this must persist server-side so it works across devices.
+
+### Hidden widget options
+
+In `index.ts`, add hidden text options:
+
+```typescript
+columnOrder: factory.text({ defaultValue: "" }),
+columnWidths: factory.text({ defaultValue: "" }),
+```
+
+With visibility override:
+
+```typescript
+{
+  columnOrder: { shouldHide: () => true },
+  columnWidths: { shouldHide: () => true },
+}
+```
+
+### Translation keys required
+
+Even hidden options need translation keys or the translation test fails:
+
+```json
+"widget.mywidget.option.columnOrder.label": "Column order",
+"widget.mywidget.option.columnWidths.label": "Column widths"
+```
+
+### Dynamic storeKey
+
+Use a key that includes `itemId` and sorted column names. This prevents cross-widget localStorage bleeding:
+
+```typescript
+const storeKey = `mytable-${itemId ?? "preview"}-${[...options.columns].toSorted().join(",")}`;
+```
+
+### Hydration from server → localStorage
+
+On mount, seed `useDataTableColumns` with server-persisted values. Use a `hydrated` ref to prevent the persist effect from immediately writing defaults back:
+
+```typescript
+const {
+  effectiveColumns,
+  columnsOrder,
+  columnsWidth,
+  setColumnsOrder,
+  setMultipleColumnWidths,
+} = useDataTableColumns<MyRow>({ key: storeKey, columns });
+
+const lastStoreKey = useRef(storeKey);
+const hydrated = useRef(false);
+
+useEffect(() => {
+  if (lastStoreKey.current !== storeKey) {
+    lastStoreKey.current = storeKey;
+    hydrated.current = false;
+  }
+  if (hydrated.current) return;
+  if (savedOrder.length > 0) setColumnsOrder(savedOrder);
+  if (Object.keys(savedWidths).length > 0) {
+    setMultipleColumnWidths(
+      Object.entries(savedWidths).map(([accessor, w]) => ({
+        accessor,
+        width: w,
+      })),
+    );
+  }
+  requestAnimationFrame(() => {
+    hydrated.current = true;
+  });
+}, [
+  storeKey,
+  savedOrder,
+  savedWidths,
+  setColumnsOrder,
+  setMultipleColumnWidths,
+]);
+```
+
+### Persist localStorage → server
+
+Watch for changes and write back:
+
+```typescript
+const prevOrder = useRef(columnsOrder);
+const prevWidths = useRef(columnsWidth);
+
+useEffect(() => {
+  if (!hydrated.current) return;
+  const orderChanged =
+    JSON.stringify(columnsOrder) !== JSON.stringify(prevOrder.current);
+  const widthsChanged =
+    JSON.stringify(columnsWidth) !== JSON.stringify(prevWidths.current);
+  prevOrder.current = columnsOrder;
+  prevWidths.current = columnsWidth;
+
+  if (!orderChanged && !widthsChanged) return;
+
+  if (orderChanged)
+    persistOption({ columnOrder: JSON.stringify(columnsOrder) });
+  if (widthsChanged) {
+    const widthMap: Record<string, number> = {};
+    for (const entry of columnsWidth) {
+      const key = Object.keys(entry)[0];
+      if (!key) continue;
+      const v = entry[key as keyof typeof entry];
+      if (typeof v === "number") widthMap[key] = v;
+      else if (typeof v === "string" && v.endsWith("px"))
+        widthMap[key] = parseInt(v, 10);
+    }
+    persistOption({ columnWidths: JSON.stringify(widthMap) });
+  }
+}, [columnsOrder, columnsWidth, persistOption]);
+```
+
+The `persistOption` helper calls both `setOptions` (local state) and `saveItemOptions` (server mutation).
+
+## 5. Context Menu (Right-Click)
+
+Do NOT install `mantine-contextmenu`. Use Mantine's `Menu` + `Portal` directly:
+
+```typescript
+interface ContextMenuState {
+  x: number;
+  y: number;
+  item: MyRow;
+}
+
+const [contextMenu, setContextMenu] = useState<ContextMenuState | null>(null);
+
+const handleContextMenu = useCallback(
+  ({ record, event }: { record: MyRow; event: React.MouseEvent }) => {
+    event.preventDefault();
+    setContextMenu({ x: event.clientX, y: event.clientY, item: record });
+  },
+  [],
+);
+
+// On DataTable:
+<DataTable onRowContextMenu={handleContextMenu} />
+
+// Render:
+{contextMenu && <RowContextMenu state={contextMenu} onClose={closeContextMenu} />}
+```
+
+The menu component uses `Portal` for correct z-index:
+
+```tsx
+function RowContextMenu({
+  state,
+  onClose,
+}: {
+  state: ContextMenuState;
+  onClose: () => void;
+}) {
+  return (
+    <Portal>
+      <Menu
+        opened
+        onClose={onClose}
+        closeOnItemClick={false}
+        position="right-start"
+        offset={0}
+      >
+        <Menu.Target>
+          <Box
+            style={{
+              position: "fixed",
+              left: state.x,
+              top: state.y,
+              width: 0,
+              height: 0,
+            }}
+          />
+        </Menu.Target>
+        <Menu.Dropdown>
+          <Menu.Item
+            onClick={() => {
+              /* action */ onClose();
+            }}
+          >
+            Action
+          </Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+    </Portal>
+  );
+}
+```
+
+**Key fix:** Use `closeOnItemClick={false}` if any menu item needs a two-step confirmation (like delete → confirm). Close the menu on scroll: `onScroll={() => { if (contextMenu) closeContextMenu(); }}`.
+
+## 6. Row Expansion
+
+```typescript
+<DataTable
+  rowExpansion={{
+    trigger: "click",
+    allowMultiple: true,
+    collapseProps: {
+      transitionDuration: 200,
+      animateOpacity: true,
+      transitionTimingFunction: "ease-out",
+    },
+    content: ({ record, collapse }) => <ExpandedRow item={record} collapse={collapse} />,
+  }}
+/>
+```
+
+**Critical:** Do NOT set `onRowClick` when using `rowExpansion` with `trigger: "click"`. They conflict and the expansion won't work.
+
+## 7. Common Pitfalls & Fixes
+
+### Status indicator dots
+
+Don't use `<Badge variant="dot" />` without children — it renders a pill with empty space. Use a plain `Box`:
+
+```tsx
+<Box
+  w={8}
+  h={8}
+  style={{
+    borderRadius: "50%",
+    backgroundColor: `var(--mantine-color-${color}-filled)`,
+    flexShrink: 0,
+  }}
+/>
+```
+
+### Tooltip overflow on long text columns
+
+When a column has `ellipsis: true`, the tooltip target element can still extend beyond the cell bounds if inner elements don't clip. Fix:
+
+```tsx
+<Tooltip position="bottom-start" ...>
+  <Group style={{ overflow: "hidden" }}>
+    ...
+  </Group>
+</Tooltip>
+```
+
+Use `position="bottom-start"` instead of `position="right"` so the tooltip never escapes the widget horizontally.
+
+### Dark mode tooltips
+
+Mantine tooltips default to the theme's tooltip color which may be white in light mode and stay white in dark mode. Always set `color="dark"` on informational tooltips inside widgets.
+
+### Division by zero
+
+Guard all ratio calculations:
+
+```typescript
+if (item.size > 0) ratio = item.sent / item.size;
+if (totalDown > 0) ratio = totalUp / totalDown;
+```
+
+### Composite idAccessor
+
+When rows can come from multiple integrations, IDs may collide. Use a composite key:
+
+```typescript
+idAccessor={(record) => `${record.integration.id}:${record.id}`}
+```
+
+### JSON option parsing
+
+Always wrap in try/catch:
+
+```typescript
+function parseJsonOption<T>(value: string | undefined, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+```
+
+### Clipboard API
+
+`navigator.clipboard.writeText()` can throw in non-HTTPS contexts. Always catch:
+
+```typescript
+void navigator.clipboard.writeText(text).catch(() => {});
+```
+
+### Sync sortStatus with widget options
+
+If the widget has configurable default sort, sync it:
+
+```typescript
+useEffect(() => {
+  setSortStatus({
+    columnAccessor: options.defaultSort,
+    direction: defaultSortDirection,
+  });
+}, [options.defaultSort, defaultSortDirection]);
+```
+
+## 8. Accessibility
+
+- All `ActionIcon` components need `aria-label`
+- Filter toggles (client badges, status badges) need `aria-pressed={isActive}`
+- `textSelectionDisabled` on DataTable prevents accidental text selection during drag/resize
+
+## 9. Error Handling
+
+- Every mutation needs an `onError` callback with `showErrorNotification`
+- The `saveItemOptions` mutation (column persistence) also needs `onError`
+- Check `isError` on the main query and show a fallback UI
+- Use a shared `mutationOptions` object to avoid repeating `onSettled`/`onError`:
+
+```typescript
+const mutationOptions = {
+  onSettled: () => void utils.myQuery.invalidate(),
+  onError: () =>
+    showErrorNotification({
+      title: t("errors.actionFailed"),
+      message: t("errors.actionFailedMessage"),
+    }),
+};
+```
+
+## 10. i18n
+
+- No hardcoded strings. Every user-visible string goes through `useScopedI18n`
+- Column titles: `t("items.{accessor}.columnTitle")`
+- Detail labels: `t("items.{accessor}.detailsTitle")`
+- States: `t("states.{state}")`
+- Actions: `t("actions.{action}")`
+- Errors: `t("errors.{errorKey}")`
+- Hidden options still need `.label` translation keys
+
+## 11. Edit Mode
+
+Disable pointer events on the table during edit mode to prevent conflicts with the board's drag-and-drop:
+
+```typescript
+let tablePointerEvents: React.CSSProperties["pointerEvents"];
+if (isEditMode) tablePointerEvents = "none";
+
+let rowContextMenuHandler = handleContextMenu;
+if (isEditMode) rowContextMenuHandler = undefined;
+
+<DataTable style={{ pointerEvents: tablePointerEvents }} />
+```
+
+## 12. DataTable Props Reference (Commonly Used)
+
+```typescript
+<DataTable
+  records={sortedData}
+  columns={effectiveColumns}
+  storeColumnsKey={storeKey}
+  withTableBorder={false}
+  borderRadius={0}
+  highlightOnHover
+  striped="odd"
+  stripedColor={{ dark: "dark.7", light: "gray.0" }}
+  highlightOnHoverColor={{ dark: "dark.5", light: "gray.1" }}
+  verticalAlign="center"
+  fetching={isFetching && data.length === 0}
+  loaderBackgroundBlur={2}
+  fz={size.fontSize}
+  textSelectionDisabled
+  sortStatus={sortStatus}
+  onSortStatusChange={setSortStatus}
+  noRecordsText={t("errors.noItems")}
+  idAccessor={(record) => record.uniqueKey}
+  height="100%"
+  className="my-table"
+  defaultColumnProps={{
+    noWrap: true,
+    draggable: true,
+    resizable: true,
+    cellsStyle: () => ({ padding: `${size.cellPadding}px 8px` }),
+  }}
+  scrollAreaProps={{ type: "auto", scrollbarSize: 6 }}
+  rowBackgroundColor={(record) => conditionalBgMap[record.state]}
+  onRowContextMenu={handleContextMenu}
+  rowExpansion={{ ... }}
+  onScroll={() => { if (contextMenu) closeContextMenu(); }}
+/>
+```
+
+## 13. Layout Stability
+
+- Don't use `table-layout: fixed` — it fights mantine-datatable's resize logic
+- Give non-name columns explicit `width` values so only the name column flexes
+- Use `ellipsis: true` on the name column — it handles `text-overflow: ellipsis` internally
+- Names should truncate at the cell boundary, not a character count, so the layout is stable regardless of content length
+- `flexShrink: 0` on badges/icons prevents them from being squeezed by long names
+
+## 14. Checklist for Each Migration
+
+1. Replace imports (`mantine-react-table` → `mantine-datatable`)
+2. Convert column definitions (`accessorKey` → `accessor`, `header` → `title`, `Cell` → `render`, etc.)
+3. Implement manual sorting with `useState` + `useMemo`
+4. Add CSS file for transparent backgrounds (if widget context)
+5. Add responsive column visibility (if widget context)
+6. Add hidden options + hydration logic (if column persistence needed)
+7. Add translation keys (including hidden option labels)
+8. Add context menu if row actions exist
+9. Add row expansion if detail view exists
+10. Add error handling on all mutations
+11. Add accessibility attributes
+12. Test at multiple widget widths
+13. Update docs in `apps/docs/docs/widgets/` if applicable
+14. Run `pnpm turbo typecheck`
+15. Run translation spec — catches missing keys

.agents/skills/documentation-sync/SKILL.md

@@ -1,51 +1,44 @@
 ---
 name: documentation-sync
-description: Keep Homarr's Docusaurus documentation aligned with user-facing code. Use when adding or changing integrations, widgets, APIs, environment variables, CLI commands, authentication, permissions, cron jobs, settings, or UI behavior that users must understand.
+description: Keep Homarr documentation in sync with code changes. Use when modifying code that affects user-facing behavior, or when adding/modifying widgets, integrations, cron jobs, API routes, env vars, permissions, auth providers, or UI in apps/docs. Covers the docs/ mapping table, integration doc pattern, and widget doc pattern.
 ---
 
 # Documentation Sync
 
-Update `apps/docs/` in the same change as user-facing behavior. Inspect adjacent pages and the docs types before copying a pattern; the source and docs evolve together.
+When modifying code that affects user-facing behavior, you MUST also update the documentation in `apps/docs/`.
 
-## Map the change
+## What triggers a doc update
 
-| Code change                         | Documentation target                                                 |
-| ----------------------------------- | -------------------------------------------------------------------- |
-| New integration                     | `apps/docs/docs/integrations/<slug>/index.mdx` and `index.ts`        |
-| New widget                          | `apps/docs/docs/widgets/<slug>/index.mdx` and `index.ts`             |
-| Changed public or management API    | `apps/docs/docs/management/api/index.mdx`                            |
-| New or changed environment variable | Relevant page under `apps/docs/docs/advanced/` or installation docs  |
-| New or changed CLI command          | `apps/docs/docs/advanced/command-line/`                              |
-| Authentication/provider change      | Relevant SSO or authentication page under `apps/docs/docs/advanced/` |
-| UI or workflow change               | Relevant getting-started, management, widget, or integration page    |
-| Cron-job behavior                   | `apps/docs/docs/management/tasks.mdx`                                |
-| Permission behavior                 | `apps/docs/docs/management/users.mdx` and the affected feature page  |
-| Custom Widget or Workshop behavior  | Relevant Custom Widget, Assistant, or Workshop documentation         |
+| Code change            | Doc location                                                |
+| ---------------------- | ----------------------------------------------------------- |
+| New integration        | `apps/docs/docs/integrations/<slug>/index.mdx` + `index.ts` |
+| New widget             | `apps/docs/docs/widgets/<slug>/index.mdx` + `index.ts`      |
+| Changed API surface    | `apps/docs/docs/management/api.mdx`                         |
+| New/changed env vars   | `apps/docs/docs/advanced/`                                  |
+| New CLI commands       | `apps/docs/docs/advanced/command-line/`                     |
+| Changed auth providers | `apps/docs/docs/advanced/` SSO pages                        |
+| UI/UX changes          | Relevant getting-started or management pages                |
+| New cron job           | `apps/docs/docs/management/tasks.mdx`                       |
+| Changed permissions    | `apps/docs/docs/management/users.mdx`                       |
 
-If no existing row fits, search by the user-visible term and update the page where a user would look for the behavior:
+## Integration doc pattern
 
-```bash
-rg -n "<term>" apps/docs/docs apps/docs/src
-```
+Each integration has a folder under `apps/docs/docs/integrations/<slug>/`:
 
-## Follow existing typed patterns
+- `index.ts` — exports a typed `IntegrationDefinition` with name, description, iconUrl, path
+- `index.mdx` — uses shared components: `IntegrationHeader`, `IntegrationCapabilites`, `IntegrationSecrets`
+- Import metadata from `@homarr/definitions` where possible
 
-For an integration:
+## Widget doc pattern
 
-- Add or update `apps/docs/docs/integrations/<slug>/index.ts` with the local `IntegrationDefinition` pattern.
-- Add or update `index.mdx` with the established `IntegrationHeader`, `IntegrationCapabilites`, and `IntegrationSecrets` components as applicable.
-- Reuse metadata from `@homarr/definitions` when the docs app already exposes it.
+Each widget has a folder under `apps/docs/docs/widgets/<slug>/`:
 
-For a widget:
+- `index.ts` — exports a typed `WidgetDefinition` with icon, name, description, path, configuration
+- `index.mdx` — uses shared components: `WidgetHeader`, `WidgetConfig`, `WidgetAdding`
 
-- Add or update `apps/docs/docs/widgets/<slug>/index.ts` with the local `WidgetDefinition` pattern.
-- Add or update `index.mdx` with the established `WidgetHeader`, `WidgetConfig`, and `AddingWidget` components as applicable.
-- Document options, required integrations, permissions, empty states, and changed behavior that affect setup or use.
+## Development
 
-## Completion criteria
-
-1. Describe the shipped behavior, not an implementation plan.
-2. Keep names, defaults, paths, screenshots, links, and prerequisites consistent with code.
-3. Update every affected page and remove superseded guidance.
-4. Run the narrowest useful docs validation. Use `pnpm turbo build --filter=@homarr/docs` when links, MDX, generated definitions, or navigation can fail; otherwise run the docs package formatter on touched files.
-5. Treat broken links and anchors as failures; Docusaurus checks them strictly.
+- Run docs locally: `pnpm dev:docs` from root
+- Build docs: `pnpm turbo build --filter=@homarr/docs`
+- The docs app can import from `@homarr/definitions` for type-safe integration/widget metadata
+- Docusaurus strict mode throws on broken links — fix any broken references before committing

.agents/skills/documentation-sync/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Homarr Documentation Sync"
-  short_description: "Keep user-facing docs aligned with code"
-  default_prompt: "Use $documentation-sync to map this Homarr code change to the required documentation updates."

.agents/skills/homarr-custom-widget/SKILL.md

@@ -1,43 +0,0 @@
----
-name: homarr-custom-widget
-description: Author, validate, preview, test, install, or configure API-backed Homarr Custom JSX v2 widgets.
----
-
-# Homarr Custom Widget
-
-Author one widget or a coordinated set of widgets. Load only needed release-matched context. Run lifecycle tools alone; independent reads may run together. For a set, research once and finish each widget's validation, evidence, and persistence before the next.
-
-1. Read primary API documentation. Use web search when documentation is not supplied or may have changed.
-2. Create credential-free definitions with keyed `sources`, `requests`, optional `options`, and safe JSX `template`.
-3. While drafting, use `customWidget_validateTemplate` for focused JSX diagnostics without resending the manifest.
-4. Send the definition once to `customWidget_previewCreate` and test its queries/actions. For a JSX-only fix, validate, call `customWidget_previewReviseTemplate` with its session, and retest; it inherits the manifest and resets evidence. Create a preview only for source/request/option changes.
-5. Configure deployment-specific source URLs and credentials through Homarr; never repeat plaintext.
-6. Persist each exact final tested preview with `customWidget_createFromPreview`. Do not resend a large definition through `customWidget_create` when a preview session is available.
-
-Treat a supplied sample or successful preview response as the binding contract. Render every core requested field, guard optional arrays and nested values before indexing, and do not silently drop returned items. Humanize numeric enums with indexed literal label arrays, omit absent numeric values instead of inventing zero, and label timestamp timezones. Give recoverable load errors and empty states a clear refresh or retry path.
-
-Use `{option:name}` or `$option` for saved options. Use `{param:name}` or `$param` for values supplied by `SubFetch`, `ActionButton`, or `ToggleSwitch`. Load queries cannot use invocation parameters. Render load queries from `data` and `status` with `RefreshButton`; reserve `SubFetch` for manual parameterized queries. Templates read `data`, `status`, `options`, and temporary `inputs`.
-
-For a bound control that depends on another input, declare its default and set `resetKey` to that scalar dependency. For example, `<Pagination bind="page" defaultValue={1} resetKey={inputs.search} />` restores page 1 when a search changes without fetching by itself.
-
-`SubFetch` with `trigger="manual"` renders its own load button. Pass a card or image through `triggerContent` with `triggerAriaLabel` when that content should launch the request. Its callback is `(result, meta)`; callback names must not shadow the reserved roots `data`, `status`, `options`, or `inputs`. Never author `onClick` or a fetch callback. Use `Icon` or `TablerIcon` with a `name`; never invent an `IconFoo` component.
-
-Plan capabilities. Use one `customWidget_findComponents` search per job. Batch selected non-obvious binding or interaction documentation with `customWidget_getComponents`; reserve `customWidget_getComponent` for one unknown-prop repair. Failed validation reopens discovery; otherwise search only for a missing capability. The full catalog is for broad exploration; load at most one example. Context never limits composition. Prefer clear hierarchy, responsive grids, divided lists, and aligned actions over nested row cards.
-
-Do not simplify a useful workflow merely because the template is interpreted. Freely compose any supported installed components with multiple sources, requests, options, `choicesFrom`, bound filters, charts, responsive detail areas, manual queries, and safe actions when they improve the user's job. Complexity must remain purposeful rather than decorative.
-
-Polish with a divided list or responsive media grid. Make one metric/action asymmetrically primary; keep headers compact, identity/state clear, metadata quiet, and one badge. At base artwork fills its row and caps above xs; never combine full-width media and nowrap.
-
-Make initial states actionable and wrap variable labels/values on narrow tiles. Do not use an unlabeled decorative icon as an empty state.
-
-Do not use imports, hooks, refs, raw HTML, raw event callbacks, browser requests, arbitrary functions, eval, bigint, npm packages, authored statement blocks, IIFEs, or recursion. Do not pretend MCP tools exist in an offline chat session.
-
-For a community widget, use `customWidget_workshopSearch`, `customWidget_workshopGet`, then `customWidget_workshopInstall`; configure its source securely. Preview configuration expires, so create before persisting configuration.
-
-Reference routing:
-
-- Load `schema` once before a new manifest; otherwise only for concrete request or option ambiguity.
-- Load `runtime` for bound inputs, manual queries, actions, or other interaction.
-- Load `security` once for any authenticated source or mutation, or to resolve a URL or interpreter limitation.
-
-Repository installations expose these as files under `references/`. MCP clients can call `customWidget_getReference` or read `homarr://custom-widgets/references/{name}` instead of loading every reference.

.agents/skills/homarr-custom-widget/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Homarr Custom Widget"
-  short_description: "Build and deploy safe Custom JSX widgets"
-  default_prompt: "Use $homarr-custom-widget to author, validate, preview, and configure a safe Custom JSX v2 widget."

.agents/skills/homarr-custom-widget/references/runtime.md

@@ -1,37 +0,0 @@
-# Runtime
-
-Templates read `data.requestId`, `status.requestId`, `options.name`, and temporary `inputs.name`. Status is `{ loading, ok, status, statusText, error }`. Render load queries directly from `data` and `status` with `RefreshButton`; never wrap them in `SubFetch`.
-
-`bind="search"` creates an in-memory input. It is never persisted. Supply invocation values only through `params`, for example:
-
-```jsx
-<TextInput bind="search" label="Search" />
-<Pagination bind="page" resetKey={inputs.search} defaultValue={1} total={5} />
-<SubFetch requestId="search" trigger="manual" params={{ query: inputs.search }}>
-  {(result) => <Stack>{(result.results ?? []).map(item => <Text key={item.id}>{item.name}</Text>)}</Stack>}
-</SubFetch>
-```
-
-Manual queries require `trigger: "manual"` on request and `SubFetch`; otherwise they run automatically. `triggerContent` with `triggerAriaLabel` makes custom content the launcher. `SubFetch` owns loading/error/retry; its child receives success plus `{ ok, status, statusText, loading: false }`. Never author `onClick` or fetch callbacks.
-
-`SubFetch`, `ActionButton`, and `ToggleSwitch` need literal `requestId`; validation rejects missing/computed IDs.
-
-Inside a successful manual result, `<RefreshButton requestId="search" label="Run again" />` reruns the same parameters.
-
-When a manual SubFetch request ID, parameters, or effective definition changes, Homarr immediately hides its prior result and returns to the trigger. It cannot fetch the new parameters until the user triggers it again.
-
-The `SubFetch` callback receives the entire JSON response exactly as previewed. If the response is `{ "results": [...] }`, render and map `result.results`; never map the envelope itself. Trace every rendered field from the preview response before persistence.
-
-Format timestamps with safe static helpers; never use `new Date`. Never invent a formatter component. Use `Date.toLocaleString(value, "en-US", "UTC")` plus a visible `UTC` label. Also available: `Date.toISOString`, `Date.toLocaleDateString`, and `Date.toLocaleTimeString`.
-
-For compact numeric enums, index a literal label array with a fallback:
-
-```jsx
-<Text>{["Unknown", "Pending", "Ready"][(item.status ?? 1) - 1] ?? "Unknown"}</Text>
-```
-
-Every stateful control must use `bind`, and its `inputs.<name>` value must feed a supported request/helper when it is meant to change remote data. For dependent pagination, declare `defaultValue={1}` and use `resetKey={inputs.search}` to restore page 1 when the query changes. If a control cannot affect the workflow through a binding, option, or runtime helper, render concise context instead of a dead control.
-
-Callback parameters must not shadow the reserved roots `data`, `status`, `options`, or `inputs`. Use `<Icon name="refresh" />` or `<TablerIcon name="refresh" />`; never invent components such as `<IconFoo />`.
-
-Use expression callbacks for supported collections and trusted slots. No callback blocks, IIFEs, authored recursion, or raw events. Regex is limited to safe string operations.

.agents/skills/homarr-custom-widget/references/schema.md

@@ -1,49 +0,0 @@
-# Schema
-
-```ts
-interface HomarrCustomWidgetV2 {
-  $schema: "homarr-custom-widget-v2";
-  name: string;
-  description?: string;
-  iconUrl?: string;
-  sources: Record<string, CustomWidgetSource>;
-  requests: Record<string, CustomWidgetRequest>;
-  options?: Record<string, CustomWidgetOption>;
-  template: string;
-}
-```
-
-The object key `default` is the required source ID; `default` is not a property on a source. Source properties are `name?`, `baseUrl`, `networkScope`, and `auth?`:
-
-```json
-{
-  "sources": {
-    "default": {
-      "name": "Service",
-      "baseUrl": "http://service.local:5055/api/v1",
-      "networkScope": "private",
-      "auth": { "type": "apiKeyHeader", "name": "X-Api-Key" }
-    }
-  },
-  "requests": {
-    "summary": { "path": "/summary" },
-    "search": { "trigger": "manual", "path": "/search", "query": { "q": { "$param": "query" } } },
-    "create": {
-      "kind": "action",
-      "method": "POST",
-      "path": "/items",
-      "body": { "id": { "$param": "id" } },
-      "confirmation": "Create this item?",
-      "invalidates": ["search"]
-    }
-  }
-}
-```
-
-Auth is `none`, `bearer`, `basic`, `{ "type": "apiKeyHeader", "name": "X-Api-Key" }`, or `{ "type": "apiKeyQuery", "name": "api_key" }`. A request defaults to source `default`, kind `query`, method `GET`, trigger `load`, inherited auth, and view permission. Set `trigger: "manual"` for a parameterized query. An action defaults to manual and modify permission. DELETE uses full permission and confirmation. Do not use `load: false`.
-
-Use stable real URLs for public APIs and clear suggested URLs for self-hosted services. Homarr collects the installer's server URL, network scope, and credentials as source setup; credentials remain outside the manifest.
-
-Paths use `{option:name}` and `{param:name}`; query/body references use `{ "$option": "name" }` and `{ "$param": "name" }`. Constants stay primitive (`take: 10`); `$param` is only for manual helpers, never load queries. Names and types are inferred.
-
-Every option has `label`, `control`, and `default`. Optional fields are `description`, `choices`, `choicesFrom`, `min`, `max`, `step`, `advanced`, and `group`.

.agents/skills/homarr-custom-widget/references/security.md

@@ -1,7 +0,0 @@
-# Security
-
-All requests use Homarr's protected server executor. Source origin, network scope, DNS, redirects, SSRF, rate limits, permissions, size limits, timeouts, and encrypted credential injection remain enforced.
-
-The JSX interpreter blocks imports, hooks, refs, raw event callbacks, browser requests, eval, arbitrary functions, prototype access, unsafe URLs, global CSS escape, arbitrary portals, bigint, statement blocks, IIFEs, and recursion. Regex literals must be bounded and reject backreferences, lookbehind, nested quantifiers, excessive length, and unsupported flags.
-
-Credentials are stored separately and never exported or returned to an agent. A published self-hosted source URL is only a suggestion: installers must confirm or replace private and loopback URLs for their own Homarr deployment. Source origins cannot be controlled through widget options.

.agents/skills/mcp-integration/SKILL.md

@@ -1,98 +1,110 @@
 ---
 name: mcp-integration
-description: Expose Homarr tRPC procedures safely through MCP. Use when adding or changing tRPC procedures under packages/api, adding MCP metadata, registering an eager MCP router, shaping tool inputs and descriptions, or reviewing MCP authorization, sensitive data, and destructive actions.
+description: Expose tRPC procedures as MCP tools for AI clients. Use when modifying procedures in packages/api/src/router, adding a new tRPC procedure or router, or deciding what to expose via Homarr's MCP interface. Covers .meta({ mcp }), router registration in packages/api/src/mcp.ts, input schema rules, and what to expose vs skip.
 ---
 
 # MCP Integration
 
-Expose a procedure only when an AI client should call it. Preserve the procedure's existing authorization and add MCP-specific safeguards for sensitive or destructive behavior.
+Every new tRPC procedure that provides useful functionality should be exposed as an MCP tool so AI assistants (Claude, Cursor, etc.) can use it. This is a first-class feature of Homarr.
 
-## Assess exposure
+Exposing a procedure makes it callable by any AI client with an API key. Before adding `.meta({ mcp })`, review what the tool exposes: authorization requirements, sensitive data, tenant isolation, auditability, and whether the action is destructive. Prefer exposing read-only queries over mutations unless the mutation is safe and permission-scoped. When in doubt, ask for a security review before shipping a new MCP tool.
 
-Prefer:
+## Adding MCP to a procedure
 
-- Data queries: list, search, get, health, stats, and summaries.
-- User-requested actions with explicit permission checks and bounded inputs.
-- Serializable results that do not reveal credentials or internal-only state.
-
-Skip subscriptions, session/onboarding internals, file streams, blobs, credential values, and procedures whose authorization or audit behavior is unclear. Ask for a security review when a mutation is destructive, tenant boundaries are ambiguous, or returned data is sensitive.
-
-## Add metadata
-
-Place `.meta()` before `.input()` and `.query()` or `.mutation()`:
+Add `.meta({ mcp: { enabled: true, description: "..." } })` to the procedure chain:
 
 ```typescript
-getAll: protectedProcedure
-  .meta({
-    mcp: {
-      enabled: true,
-      description: "List resources the current user can access, including stable IDs used by resource_get",
-    },
-  })
-  .input(z.object({ limit: z.number().int().min(1).max(100).default(50) }))
-  .query(async ({ ctx, input }) => {
-    // Preserve normal procedure authorization.
-  });
-```
+// Read-only tool (query)
+myProcedure: protectedProcedure
+  .meta({ mcp: { enabled: true, description: "Get all items with their status and metadata" } })
+  .input(z.object({ limit: z.number().default(10) }))
+  .query(async ({ ctx, input }) => { ... })
 
-No-input procedures can omit `.input()`; the MCP extractor accepts an empty object for them.
-
-For mutations, state the effect and required permission in the description:
-
-```typescript
-remove: permissionRequiredProcedure
-  .meta({
-    mcp: {
-      enabled: true,
-      description: "Delete one resource by ID. Requires full access; get the ID from resource_all",
-    },
-  })
+// Write tool (mutation)
+myAction: protectedProcedure
+  .meta({ mcp: { enabled: true, description: "Delete an item by ID. Requires interact permission on the integration" } })
   .input(z.object({ id: z.string() }))
-  .mutation(async ({ ctx, input }) => {
-    // Perform the permission-scoped action.
-  });
+  .mutation(async ({ ctx, input }) => { ... })
+
+// No-input procedure (z.void) — works fine, no .input() needed
+getAll: protectedProcedure
+  .meta({ mcp: { enabled: true, description: "List all resources" } })
+  .query(async ({ ctx }) => { ... })
 ```
 
-## Write discoverable descriptions
+The `.meta()` call must come **before** `.input()` and `.query()`/`.mutation()` in the chain.
 
-Include every item that applies:
+## Writing good descriptions
 
-- What the tool returns or changes.
-- Supported integrations or services.
-- Required IDs and the tool that returns them.
-- Permission requirements and the meaning of permission fields.
-- Important bounds, confirmation semantics, or irreversible effects.
+The description is the **only thing** an AI sees to decide when and how to use the tool. Write it like you're explaining to a colleague who has never used Homarr.
 
-Use precise domain language. A description such as `Get calendar events` is insufficient because it omits supported services, required IDs, and result scope.
+**Must include:**
 
-## Shape inputs for clients
+- What the tool returns or does
+- Which integrations/services it works with (if applicable)
+- How to get required IDs (e.g., "Use integration_all to get the integrationId")
+- Permission requirements (if non-obvious)
 
-- Use a top-level `z.object({...})` for parameterized tools.
-- Bound strings, arrays, numeric ranges, pagination, and payload sizes.
-- Use defaults where a safe, unsurprising value exists.
-- Prefer explicit fields over a top-level union or discriminated union.
-- Keep identifiers stable and describe how to obtain them.
-- Keep secrets out of inputs unless the procedure is explicitly a credential-configuration flow with server-owned encryption and non-return guarantees.
+**Good:**
 
-## Register the eager router
+```text
+"Get calendar events for upcoming and recent media releases. Fetches from all connected Sonarr (TV), Radarr (movies), Lidarr (music), and Readarr (books) integrations. Requires integrationIds from integration_all"
+```
 
-The application router in `packages/api/src/root.ts` is lazy. MCP tool extraction is synchronous, so add an eager import and registration in `packages/api/src/mcp.ts`:
+**Bad:**
+
+```text
+"Get calendar events"
+```
+
+**For tools that return permission fields**, explain what they mean:
+
+```text
+"List all integrations. Returns permissions.hasUseAccess (read) and permissions.hasInteractAccess (actions) — false means the API key lacks that permission, not an error"
+```
+
+## Registering in the MCP router
+
+After adding `.meta()` to procedures, you must register the router in `packages/api/src/mcp.ts`. This file uses **eager imports** (no `lazy()`) because MCP tool extraction requires synchronous access to all procedure definitions.
 
 ```typescript
-import { resourceRouter } from "./router/resource";
+// packages/api/src/mcp.ts
+import { myNewRouter } from "./router/my-new-feature";
 
 export const mcpRouter = createTRPCRouter({
-  resource: resourceRouter,
+  // ... existing routers
+  myFeature: myNewRouter,
 });
 ```
 
-Register the smallest router that owns the enabled procedures. If a parent router uses `lazy()`, import the needed subrouter directly. Metadata on a procedure is not enough; a procedure absent from `mcpRouter` is not exposed.
+**If your router is nested** (e.g., widget sub-routers), import and register the sub-router directly — do not import a parent that uses `lazy()`.
 
-## Validate the tool surface
+## What to expose vs. what to skip
 
-1. Confirm the procedure still enforces its ordinary auth and permission boundary.
-2. Confirm `packages/api/src/mcp.ts` eagerly includes the procedure.
-3. Confirm the generated tool name, description, and JSON schema are unambiguous.
-4. Run the focused API MCP spec when the tool list or extraction changes: `pnpm test packages/api/src/test/mcp.spec.ts`.
-5. Run the focused route spec when protocol or transport behavior changes: `pnpm test apps/nextjs/src/app/api/mcp/[transport]/route.spec.ts`.
-6. If manually probing `/api/mcp/<transport>`, use a scoped API key and avoid printing credentials or secret-bearing results.
+**Expose:**
+
+- Data queries (list, search, get by ID)
+- Actions users would ask an AI to do (toggle, create, delete, approve)
+- Status checks (health, stats, summaries)
+
+**Skip:**
+
+- Subscriptions (WebSocket-only, not supported by MCP)
+- Internal procedures (session management, onboarding steps)
+- File upload/download procedures
+- Procedures that return non-serializable data (streams, blobs)
+
+## Input schema rules
+
+- Use `z.object({...})` for inputs — this maps cleanly to MCP tool parameters
+- `z.void()` (no `.input()`) works — the MCP handler patches these to accept empty objects
+- Avoid `z.union()` or `z.discriminatedUnion()` at the top level — AI clients struggle with these
+- Use `.default()` on optional fields so the AI doesn't need to guess values
+
+## Checklist for new features
+
+1. Add `.meta({ mcp: { enabled: true, description: "..." } })` to relevant procedures
+2. Import and register the router in `packages/api/src/mcp.ts` (eager, no lazy)
+3. Write descriptions that explain what the tool does, what it needs, and what it returns
+4. If the tool requires an ID from another tool, say which one in the description
+5. Test with `curl` against `/api/mcp/mcp` to verify the tool appears in `tools/list`

.agents/skills/mcp-integration/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Homarr MCP Integration"
-  short_description: "Expose tRPC procedures safely through MCP"
-  default_prompt: "Use $mcp-integration to expose this Homarr tRPC procedure as a safe, discoverable MCP tool."

.deepsource.toml

@@ -0,0 +1,8 @@
+version = 1
+
+[[analyzers]]
+name = "javascript"
+
+[analyzers.meta]
+plugins = ["react"]
+environment = ["nodejs"]

.env.example

@@ -61,31 +61,9 @@ TURBO_TELEMETRY_DISABLED=1
 # Enable mock integration
 UNSAFE_ENABLE_MOCK_INTEGRATION=true
 
-# Public URL contract. Values must be absolute HTTP(S) URLs without credentials,
-# query strings, or fragments. Trailing slashes are normalized at startup.
-HOMARR_WEBSITE_URL=https://homarr.dev
-# PocketBase API used by Homarr and by the standalone documentation site.
-# Defaults to HOMARR_WEBSITE_URL.
-# WORKSHOP_API_URL=https://homarr.dev
-# Public Workshop website used by links in Homarr, Custom Widgets, onboarding,
-# and assistant context. Defaults to HOMARR_WEBSITE_URL/workshop.
-# WORKSHOP_WEB_URL=https://homarr.dev/workshop
-
-# Documentation and PocketBase deployment settings.
-# WORKSHOP_PUBLIC_ORIGIN=https://homarr.dev
-# PB_ALLOWED_ORIGINS=*
-
-# Local Workshop stack:
-# HOMARR_WEBSITE_URL=http://127.0.0.1:3003
-# WORKSHOP_API_URL=http://127.0.0.1:8090
-# WORKSHOP_WEB_URL=http://127.0.0.1:3003/workshop
-# WORKSHOP_PUBLIC_ORIGIN=http://127.0.0.1:3003
-# Optional: GITHUB_CLIENT_ID=
-# Optional: GITHUB_CLIENT_SECRET=
-
 # Enable demo mode (seeds a demo user "demo"/"demo", a sample board and a mock integration)
 # DEMO_MODE=true
 
 # Whether demo mode is read-only. Defaults to true (the public demo blocks all mutations).
 # Set to false for writable preview deployments so the demo user can modify the dashboard.
-# DEMO_READ_ONLY=false
+# DEMO_READ_ONLY=false

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -33,9 +33,6 @@ body:
       options:
         # The below comment is used to insert a new version with on-release.yml
         #NEXT_VERSION#
-        - 1.76.2
-        - 1.76.1
-        - 1.76.0
         - 1.75.0
         - 1.74.0
         - 1.73.0

.github/actions/extract-build-artifact/action.yaml

@@ -20,7 +20,7 @@ runs:
   using: "composite"
   steps:
     - name: Prebuilt debian dependencies
-      uses: ./.github/actions/prebuilt-debian
+      uses: homarr-labs/homarr/.github/actions/prebuilt-debian@dev
       id: prebuilt-debian
       with:
         architecture: ${{ inputs.architecture }}

.github/actions/prebuilt-debian/action.yaml

@@ -11,6 +11,9 @@ outputs:
 runs:
   using: "composite"
   steps:
+    - uses: actions/checkout@v7
+      with:
+        persist-credentials: false
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v4
 

.github/pull_request_template.md

@@ -16,6 +16,6 @@
 **When contributing a new integration or widget:**
 
 - [ ] I confirmed manually that the integration or widget is working with a real system and performed basic smoke
-      tests (e.g. what happens if it is offline)
+  tests (e.g. what happens if it is offline)
 - [ ] Optional but recommended: I confirm that I am willing to be added to the `CODEOWNERS` of this feature and will
-      provide support and maintain the integration (e.g. in case of breaking or failure)
+  provide support and maintain the integration (e.g. in case of breaking or failure)

.github/workflows/autofix.yml

@@ -1,35 +1,47 @@
-name: Formatting
+name: Auto-fix lint and format
 
 on:
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: ["**"]
+    branches: ["*"]
 
 permissions:
-  contents: read
+  contents: write
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
-  format:
-    name: Check formatting
+  autofix:
+    name: Auto-fix
+    if: github.event.pull_request.head.repo.id == github.repository_id
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-          persist-credentials: false
+          ref: ${{ github.head_ref }}
 
       - name: Setup
         uses: ./tooling/github/setup
 
-      - name: Check changed files
+      - name: Get changed files
+        id: changed
         env:
           BASE_REF: ${{ github.base_ref }}
         run: |
-          git diff --name-only --diff-filter=ACMR -z "origin/${BASE_REF}...HEAD" -- \
-            '*.css' '*.js' '*.json' '*.jsonc' '*.jsx' '*.md' '*.mdx' '*.scss' '*.ts' '*.tsx' '*.yaml' '*.yml' \
-            | xargs -0 -r pnpm exec oxfmt --check --
+          git diff --name-only --diff-filter=ACMR "origin/${BASE_REF}...HEAD" -- '*.ts' '*.tsx' '*.js' '*.jsx' > /tmp/changed-files
+          echo "count=$(wc -l < /tmp/changed-files | tr -d '[:space:]')" >> $GITHUB_OUTPUT
+
+      - name: Auto-fix lint + format
+        if: steps.changed.outputs.count != '0'
+        run: |
+          xargs -r -a /tmp/changed-files pnpm exec oxlint --fix || true
+          xargs -r -a /tmp/changed-files pnpm exec oxfmt --write
+
+      - name: Commit fixes
+        uses: stefanzweifel/git-auto-commit-action@v7
+        with:
+          commit_message: "style: auto-fix lint and format"

.github/workflows/ci.yml

@@ -3,12 +3,12 @@ name: CI
 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
-    branches: ["**"]
+    branches: ["*"]
   pull_request_target:
     types: [closed]
-    branches: ["**"]
+    branches: ["*"]
   push:
-    branches: [main, dev, beta, next, v2, release/v2]
+    branches: [main, dev, beta, next]
   merge_group:
   workflow_dispatch:
     inputs:
@@ -34,10 +34,8 @@ permissions:
   contents: read
 
 concurrency:
-  # Every event for a PR shares one group so a close event cancels stale image
-  # publication and a newer synchronize run cannot be overwritten by an older run.
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || inputs.pr_number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.event_name == 'pull_request_target' || github.event_name == 'workflow_dispatch' || github.ref != 'refs/heads/main' }}
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || inputs.pr_number || github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 env:
   FORCE_COLOR: 3
@@ -51,7 +49,7 @@ jobs:
     name: Fast gate
     if: github.event_name != 'pull_request_target' && (github.event_name != 'workflow_dispatch' || inputs.operation != 'cleanup')
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 15
     env:
       TURBO_API: ${{ secrets.TURBO_API }}
       TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
@@ -89,36 +87,21 @@ jobs:
       - name: Validate workspace configuration
         run: pnpm lint:ws
 
-      - name: Validate Custom Widget architecture
-        run: pnpm check:custom-widgets
-
-      - name: Validate checked-in OpenAPI schema
-        run: pnpm check:openapi
-
-      - name: Validate Custom Widget bundle budget
-        run: |
-          pnpm --filter nextjs build
-          pnpm check:custom-widget-bundle
-
       - name: Run unit tests
         run: pnpm test
 
   container:
     name: Container and E2E
-    needs: [fast-gate, preview-amd64]
+    needs: fast-gate
     if: |
-      !cancelled() && needs.fast-gate.result == 'success' &&
-      (
-        github.event_name == 'merge_group' ||
-        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
-        (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
-        (github.event_name == 'workflow_dispatch' && (inputs.operation == 'validate' || inputs.operation == 'publish'))
-      )
+      github.event_name == 'merge_group' ||
+      (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+      (github.event_name == 'workflow_dispatch' && (inputs.operation == 'validate' || inputs.operation == 'publish'))
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
       contents: read
-      packages: read
+      packages: write
     steps:
       - uses: actions/checkout@v7
         if: "!env.ACT"
@@ -133,18 +116,8 @@ jobs:
         if: "!env.ACT"
         uses: docker/setup-buildx-action@v4
 
-      - name: Reuse amd64 preview image
-        if: needs.preview-amd64.outputs.digest != '' && !env.ACT
-        env:
-          DIGEST: ${{ needs.preview-amd64.outputs.digest }}
-        run: |
-          echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
-          docker pull "${PREVIEW_IMAGE}@${DIGEST}"
-          docker tag "${PREVIEW_IMAGE}@${DIGEST}" homarr-ci
-          docker tag "${PREVIEW_IMAGE}@${DIGEST}" homarr-e2e
-
       - name: Build container once
-        if: needs.preview-amd64.outputs.digest == '' && !env.ACT
+        if: "!env.ACT"
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -159,8 +132,8 @@ jobs:
             org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
             org.opencontainers.image.revision=${{ github.sha }}
             org.opencontainers.image.ref.name=pr-${{ github.event.pull_request.number || inputs.pr_number || 'none' }}
-          cache-from: type=gha,scope=homarr-e2e
-          cache-to: type=gha,scope=homarr-e2e,mode=max
+          cache-from: type=gha,scope=homarr-linux-amd64
+          cache-to: type=gha,scope=homarr-linux-amd64,mode=max
           secrets: |
             TURBO_API=${{ secrets.TURBO_API }}
             TURBO_TEAM=${{ secrets.TURBO_TEAM }}
@@ -201,10 +174,7 @@ jobs:
         run: pnpm exec playwright install-deps chromium
 
       - name: Run E2E tests
-        env:
-          NODE_ENV: development
-          CI: "true"
-        run: pnpm exec vitest e2e --retry 1 --maxWorkers 4
+        run: pnpm test:e2e
 
       - name: Upload E2E artifacts
         if: failure() && !env.ACT
@@ -214,189 +184,37 @@ jobs:
           path: e2e/test-results/
           retention-days: 7
 
-  preview-amd64:
-    name: Build amd64 preview image
-    needs: fast-gate
-    if: |
-      (
-        (github.event_name == 'pull_request' && github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository) ||
-        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
-        (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
-      )
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    permissions:
-      contents: read
-      packages: write
-    outputs:
-      digest: ${{ steps.preview-build.outputs.digest }}
-    steps:
-      - uses: actions/checkout@v7
-        if: "!env.ACT"
-        with:
-          persist-credentials: false
-          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || '' }}
-
-      - name: Log in to GHCR
-        if: "!env.ACT"
-        uses: docker/login-action@v4
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Set up Docker Buildx
-        if: "!env.ACT"
-        uses: docker/setup-buildx-action@v4
-
-      - name: Build and push amd64 preview image by digest
-        id: preview-build
-        if: "!env.ACT"
-        uses: docker/build-push-action@v7
-        with:
-          context: .
-          network: host
-          platforms: linux/amd64
-          outputs: type=image,"name=${{ env.PREVIEW_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=homarr-linux-amd64
-          cache-to: type=gha,scope=homarr-linux-amd64,mode=max
-          secrets: |
-            TURBO_API=${{ secrets.TURBO_API }}
-            TURBO_TEAM=${{ secrets.TURBO_TEAM }}
-            TURBO_TOKEN=${{ secrets.TURBO_TOKEN }}
-            TURBO_REMOTE_CACHE_SIGNATURE_KEY=${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
-
-  preview-arm64:
-    name: Build arm64 preview image
-    needs: fast-gate
-    if: |
-      (
-        (github.event_name == 'pull_request' && github.event.pull_request.draft == false && github.event.pull_request.head.repo.full_name == github.repository) ||
-        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
-        (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
-      )
-    runs-on: ubuntu-24.04-arm
-    timeout-minutes: 20
-    permissions:
-      contents: read
-      packages: write
-    outputs:
-      digest: ${{ steps.preview-build.outputs.digest }}
-    steps:
-      - uses: actions/checkout@v7
-        if: "!env.ACT"
-        with:
-          persist-credentials: false
-          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || '' }}
-
-      - name: Log in to GHCR
-        if: "!env.ACT"
-        uses: docker/login-action@v4
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Set up Docker Buildx
-        if: "!env.ACT"
-        uses: docker/setup-buildx-action@v4
-
-      - name: Build and push arm64 preview image by digest
-        id: preview-build
-        if: "!env.ACT"
-        uses: docker/build-push-action@v7
-        with:
-          context: .
-          network: host
-          platforms: linux/arm64
-          outputs: type=image,"name=${{ env.PREVIEW_IMAGE }}",push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=homarr-linux-arm64
-          cache-to: type=gha,scope=homarr-linux-arm64,mode=max
-          secrets: |
-            TURBO_API=${{ secrets.TURBO_API }}
-            TURBO_TEAM=${{ secrets.TURBO_TEAM }}
-            TURBO_TOKEN=${{ secrets.TURBO_TOKEN }}
-            TURBO_REMOTE_CACHE_SIGNATURE_KEY=${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
-
-  publish-preview:
-    name: Publish multi-platform preview image
-    needs: [container, preview-amd64, preview-arm64]
-    if: |
-      !cancelled() &&
-      needs.container.result == 'success' &&
-      needs.preview-amd64.result == 'success' &&
-      needs.preview-arm64.result == 'success' &&
-      (
-        (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
-        (github.event_name == 'push' && github.ref == 'refs/heads/release/v2') ||
-        (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
-      )
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      packages: write
-      pull-requests: read
-    env:
-      PREVIEW_TAG: ${{ github.event_name == 'push' && 'v2' || format('pr-{0}', github.event.pull_request.number || inputs.pr_number) }}
-    steps:
-      - name: Log in to GHCR
-        if: "!env.ACT"
-        uses: docker/login-action@v4
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Set up Docker Buildx
-        if: "!env.ACT"
-        uses: docker/setup-buildx-action@v4
-
-      - name: Verify PR head before publication
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v8
+      - name: Determine preview tag
+        id: preview
+        if: |
+          !env.ACT &&
+          (
+            (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) ||
+            (github.event_name == 'workflow_dispatch' && inputs.operation == 'publish')
+          )
         env:
-          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr_number }}
+        run: echo "tag=pr-${PR_NUMBER}" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to GHCR
+        if: steps.preview.outputs.tag != ''
+        uses: docker/login-action@v4
         with:
-          script: |
-            const { data: pull } = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: context.payload.pull_request.number,
-            });
-            if (pull.state !== "open") {
-              core.setFailed(`PR #${pull.number} is ${pull.state}; refusing to publish its preview.`);
-              return;
-            }
-            if (pull.head.sha !== process.env.EXPECTED_HEAD_SHA) {
-              core.setFailed(`PR #${pull.number} moved from ${process.env.EXPECTED_HEAD_SHA} to ${pull.head.sha}.`);
-            }
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Publish preview manifest
-        if: "!env.ACT"
+      - name: Push preview image
+        if: steps.preview.outputs.tag != ''
         env:
-          AMD64_DIGEST: ${{ needs.preview-amd64.outputs.digest }}
-          ARM64_DIGEST: ${{ needs.preview-arm64.outputs.digest }}
+          PREVIEW_TAG: ${{ steps.preview.outputs.tag }}
         run: |
-          tags=(-t "${PREVIEW_IMAGE}:${PREVIEW_TAG}")
-          docker buildx imagetools create "${tags[@]}" \
-            "${PREVIEW_IMAGE}@${AMD64_DIGEST}" \
-            "${PREVIEW_IMAGE}@${ARM64_DIGEST}"
+          docker tag homarr-ci "${PREVIEW_IMAGE}:${PREVIEW_TAG}"
+          docker push "${PREVIEW_IMAGE}:${PREVIEW_TAG}"
 
-      - name: Verify preview manifest platforms
-        if: "!env.ACT"
-        run: |
-          tags=("${PREVIEW_TAG}")
-          for tag in "${tags[@]}"; do
-            image="${PREVIEW_IMAGE}:${tag}"
-            manifest="$(docker buildx imagetools inspect "$image" --raw)"
-            for architecture in amd64 arm64; do
-              jq --exit-status --arg architecture "$architecture" \
-                'any(.manifests[]; .platform.os == "linux" and .platform.architecture == $architecture)' \
-                <<<"$manifest" >/dev/null
-            done
-            docker buildx imagetools inspect "$image"
-          done
+      - name: Show Act publication result
+        if: env.ACT
+        run: echo "Act validated the publication path; external GHCR writes are disabled locally."
 
   cleanup:
     name: Clean up preview image
@@ -433,14 +251,6 @@ jobs:
               core.info(`No package version found with tag "${tag}"`);
               return;
             }
-            const targetTags = target.metadata?.container?.tags ?? [];
-            const extraTags = targetTags.filter((targetTag) => targetTag !== tag);
-            if (extraTags.length > 0) {
-              core.warning(
-                `Package version ${target.id} also carries tag(s) ${extraTags.map((targetTag) => `"${targetTag}"`).join(", ")}; refusing cleanup.`,
-              );
-              return;
-            }
             await github.rest.packages.deletePackageVersionForOrg({
               package_type: "container",
               package_name: packageName,

.github/workflows/deployment-docker-image.yml

@@ -13,7 +13,7 @@ on:
         type: boolean
         required: false
         default: true
-        description: Send notifications when redeploying an existing release
+        description: Send notifications
 
 permissions:
   contents: write # Required to update package.json version
@@ -38,10 +38,10 @@ jobs:
       SKIP_RELEASE: ${{ github.event_name == 'workflow_dispatch' || github.ref_name == 'dev' || github.ref_name == 'next' }}
     outputs:
       version: ${{ steps.read-semver.outputs.version || steps.version-fallback.outputs.version }}
-      git_ref: ${{ steps.read-git-ref.outputs.ref || steps.read-semver.outputs.version || github.ref }}
+      git_ref: ${{ steps.read-git-ref.outputs.ref || github.ref }}
       skipped: ${{ env.SKIP_RELEASE }}
     steps:
-      - run: echo "Manual dispatch redeploys the latest existing release without creating a new one"
+      - run: echo "Skipping release for workflow_dispatch event"
         if: env.SKIP_RELEASE == 'true'
         # The below generated version fallback represents a normalized branch name, for example "feature/branch-name" -> "feature-branch-name"
       - run: echo "version="$(echo ${{github.ref_name}} | sed 's/[^a-zA-Z0-9\-]/-/g') >> "$GITHUB_OUTPUT"
@@ -58,9 +58,8 @@ jobs:
           permission-contents: write # required to commit package.json & changelog changes, merge them to dev / next and publish the release
 
       - uses: actions/checkout@v7
-        if: env.SKIP_RELEASE == 'false' || github.ref_name == 'main' || github.ref_name == 'beta'
+        if: env.SKIP_RELEASE == 'false'
         with:
-          fetch-depth: 0
           persist-credentials: false
       - uses: pnpm/action-setup@v6
         if: env.SKIP_RELEASE == 'false'
@@ -69,29 +68,12 @@ jobs:
         with:
           node-version: 24.18.0
           package-manager-cache: false
-      - name: Verify major release intent
+      - run: npm i -g pnpm
         if: env.SKIP_RELEASE == 'false'
-        run: |
-          latest_tag="$(git describe --tags --abbrev=0)"
-          latest_major="${latest_tag#v}"
-          latest_major="${latest_major%%.*}"
-          package_version="$(jq --raw-output '.version' package.json)"
-          package_major="${package_version%%.*}"
-
-          if (( package_major <= latest_major )); then
-            exit 0
-          fi
-
-          if git log --format='%s%n%b' "${latest_tag}..HEAD" \
-            | grep --extended-regexp --quiet '(^[[:alnum:]-]+(\([^)]*\))?!:)|(^BREAKING[ -]CHANGE:)'; then
-            exit 0
-          fi
-
-          echo "::error::package.json declares ${package_version}, but commits since ${latest_tag} contain no breaking-change signal. Use a conventional ! commit or BREAKING CHANGE footer so Semantic Release creates the intended major version."
-          exit 1
       - name: Install dependencies
         if: env.SKIP_RELEASE == 'false'
-        run: pnpm install --frozen-lockfile
+        run: |
+          pnpm install
       - name: Run Semantic Release
         if: env.SKIP_RELEASE == 'false'
         env:
@@ -223,14 +205,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v7
-        if: needs.release.outputs.skipped == 'false'
-        with:
-          ref: ${{ needs.release.outputs.git_ref }}
-          persist-credentials: false
       - name: Extract amd64
         if: needs.release.outputs.skipped == 'false'
-        uses: ./.github/actions/extract-build-artifact
+        uses: homarr-labs/homarr/.github/actions/extract-build-artifact@dev
         with:
           digest: "${{ env.GHCR_REPO }}@${{ needs.build-amd64.outputs.digest }}"
           architecture: amd64
@@ -244,14 +221,9 @@ jobs:
     runs-on: ubuntu-24.04-arm
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v7
-        if: needs.release.outputs.skipped == 'false'
-        with:
-          ref: ${{ needs.release.outputs.git_ref }}
-          persist-credentials: false
       - name: Extract arm64
         if: needs.release.outputs.skipped == 'false'
-        uses: ./.github/actions/extract-build-artifact
+        uses: homarr-labs/homarr/.github/actions/extract-build-artifact@dev
         with:
           digest: "${{ env.GHCR_REPO }}@${{ needs.build-arm64.outputs.digest }}"
           architecture: arm64
@@ -312,7 +284,6 @@ jobs:
           gh release edit --repo ${{ github.repository }} ${{ needs.release.outputs.version }} --draft=false
 
       - name: Discord notification
-        if: github.event_name != 'workflow_dispatch' || inputs['send-notifications']
         env:
           DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
         uses: Ilshidur/action-discord@0.4.0

.github/workflows/on-pr-prebuilt-debian-validate.yml

@@ -5,7 +5,7 @@ permissions:
 
 on:
   pull_request:
-    branches: ["**"]
+    branches: ["*"]
     paths: [".github/actions/prebuilt-debian/**", "deployments/prebuilt-debian/**"]
 
 jobs:

.github/workflows/on-pr-renovate-validate.yml

@@ -5,7 +5,7 @@ permissions:
 
 on:
   pull_request:
-    branches: ["**"]
+    branches: ["*"]
     paths: [".github/renovate.json5"]
 
 jobs:

.github/workflows/skip-renovate-stability-days.yml

@@ -1,6 +1,5 @@
 permissions:
   statuses: write
-  contents: read
 
 on:
   pull_request:
@@ -17,20 +16,12 @@ jobs:
         env:
           GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
         run: |
-          for attempt in 1 2 3 4 5; do
-            if gh api \
-              --method POST \
-              -H "Accept: application/vnd.github+json" \
-              -H "X-GitHub-Api-Version: 2022-11-28" \
-              /repos/${{github.repository}}/statuses/${{github.event.pull_request.head.sha}} \
-              -f 'state=success' \
-              -f 'target_url=https://docs.renovatebot.com/configuration-options#minimumreleaseage' \
-              -f 'description=Skipped for non renovate branches' \
-              -f 'context=renovate/stability-days' \
-              --silent; then
-              exit 0
-            fi
-            echo "status POST failed (attempt $attempt/5), retrying in 5s"
-            sleep 5
-          done
-          exit 1
+          gh api \
+          --method POST \
+          -H "Accept: application/vnd.github+json" \
+          -H "X-GitHub-Api-Version: 2022-11-28" \
+          /repos/${{github.repository}}/statuses/${{github.event.pull_request.head.sha}} \
+          -f 'state=success' \
+          -f 'target_url=https://docs.renovatebot.com/configuration-options#minimumreleaseage' \
+          -f 'description=Skipped for non renovate branches' \
+          -f 'context=renovate/stability-days'

.github/workflows/update-contributors.yml

@@ -15,6 +15,9 @@ jobs:
   update-contributors:
     runs-on: ubuntu-latest
     timeout-minutes: 2
+    strategy:
+      matrix:
+        node-version: [22]
     steps:
       - name: Obtain token
         id: obtainToken
@@ -31,10 +34,10 @@ jobs:
           GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
 
       - uses: pnpm/action-setup@v6
-      - name: Use Node.js
+      - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v6
         with:
-          node-version: 24.18.0
+          node-version: ${{ matrix.node-version }}
           cache: "pnpm"
 
       - name: Run update script

.github/workflows/workshop.yml

@@ -1,146 +0,0 @@
-name: Workshop
-
-on:
-  pull_request:
-  push:
-    branches: [dev, v2, release/v2, main]
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ (github.ref_name == 'v2' || github.ref_name == 'release/v2') && 'v2-preview' || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  validate:
-    runs-on: ubuntu-24.04
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24.18.0
-      - uses: pnpm/action-setup@v6
-        with:
-          run_install: false
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm --filter @homarr/workshop typecheck
-      - run: pnpm --filter @homarr/docs typecheck
-      - run: docker compose --env-file apps/workshop/.env.staging.example -f apps/workshop/docker-compose.staging.yml config --quiet
-      - run: pnpm test:workshop
-      - run: pnpm test:workshop-image
-
-  publish-amd64:
-    if: github.event_name == 'push' && (github.ref_name == 'v2' || github.ref_name == 'release/v2' || github.ref_name == 'main')
-    needs: validate
-    runs-on: ubuntu-24.04
-    timeout-minutes: 20
-    permissions:
-      contents: read
-      packages: write
-    outputs:
-      digest: ${{ steps.build.outputs.digest }}
-    steps:
-      - uses: actions/checkout@v7
-      - uses: docker/setup-buildx-action@v4
-      - uses: docker/login-action@v4
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - uses: docker/build-push-action@v7
-        id: build
-        with:
-          context: .
-          file: apps/workshop/Dockerfile
-          target: production
-          platforms: linux/amd64
-          outputs: type=image,"name=ghcr.io/homarr-labs/workshop",push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=workshop-linux-amd64
-          cache-to: type=gha,scope=workshop-linux-amd64,mode=max
-
-  publish-arm64:
-    if: github.event_name == 'push' && (github.ref_name == 'v2' || github.ref_name == 'release/v2' || github.ref_name == 'main')
-    needs: validate
-    runs-on: ubuntu-24.04-arm
-    timeout-minutes: 20
-    permissions:
-      contents: read
-      packages: write
-    outputs:
-      digest: ${{ steps.build.outputs.digest }}
-    steps:
-      - uses: actions/checkout@v7
-      - uses: docker/setup-buildx-action@v4
-      - uses: docker/login-action@v4
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - uses: docker/build-push-action@v7
-        id: build
-        with:
-          context: .
-          file: apps/workshop/Dockerfile
-          target: production
-          platforms: linux/arm64
-          outputs: type=image,"name=ghcr.io/homarr-labs/workshop",push-by-digest=true,name-canonical=true,push=true
-          cache-from: type=gha,scope=workshop-linux-arm64
-          cache-to: type=gha,scope=workshop-linux-arm64,mode=max
-
-  publish:
-    if: github.event_name == 'push' && (github.ref_name == 'v2' || github.ref_name == 'release/v2' || github.ref_name == 'main')
-    needs: [publish-amd64, publish-arm64]
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-    permissions:
-      contents: read
-      packages: write
-    env:
-      WORKSHOP_IMAGE: ghcr.io/homarr-labs/workshop
-    steps:
-      - uses: docker/setup-buildx-action@v4
-      - uses: docker/login-action@v4
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Verify branch head before publication
-        uses: actions/github-script@v8
-        with:
-          script: |
-            const branchName = context.ref.replace("refs/heads/", "");
-            const { data: branch } = await github.rest.repos.getBranch({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              branch: branchName,
-            });
-            if (branch.commit.sha !== context.sha) {
-              core.setFailed(`Branch ${branchName} moved from ${context.sha} to ${branch.commit.sha}.`);
-            }
-      - name: Publish multi-platform image
-        env:
-          AMD64_DIGEST: ${{ needs.publish-amd64.outputs.digest }}
-          ARM64_DIGEST: ${{ needs.publish-arm64.outputs.digest }}
-        run: |
-          tags=(-t "${WORKSHOP_IMAGE}:sha-${GITHUB_SHA}")
-          if [[ "${GITHUB_REF_NAME}" == "v2" || "${GITHUB_REF_NAME}" == "release/v2" ]]; then
-            tags+=(-t "${WORKSHOP_IMAGE}:v2")
-          fi
-          if [[ "${GITHUB_REF_NAME}" == "main" ]]; then
-            tags+=(-t "${WORKSHOP_IMAGE}:latest")
-          fi
-          docker buildx imagetools create "${tags[@]}" \
-            "${WORKSHOP_IMAGE}@${AMD64_DIGEST}" \
-            "${WORKSHOP_IMAGE}@${ARM64_DIGEST}"
-      - name: Verify multi-platform image
-        run: |
-          image="${WORKSHOP_IMAGE}:sha-${GITHUB_SHA}"
-          manifest="$(docker buildx imagetools inspect "$image" --raw)"
-          for architecture in amd64 arm64; do
-            jq --exit-status --arg architecture "$architecture" \
-              'any(.manifests[]; .platform.os == "linux" and .platform.architecture == $architecture)' \
-              <<<"$manifest" >/dev/null
-          done
-          docker buildx imagetools inspect "$image"

.gitignore

@@ -16,7 +16,6 @@ out/
 next-env.d.ts
 
 # artifacts
-.ai-evaluations/
 packages/db/migrations/*/migrate.cjs
 
 # nitro
@@ -25,8 +24,6 @@ packages/db/migrations/*/migrate.cjs
 
 # production
 build
-tools/homarr-dev/homarr
-tools/homarr-dev/homarr-dev
 
 # misc
 .DS_Store
@@ -83,14 +80,3 @@ apps/docs/.docusaurus
 apps/docs/build
 .pnpm-store
 benchmark-results
-
-# local performance investigation (never ship benchmark data or restored backups)
-.widget-performance/
-.bench/
-homarr-backup*.zip
-*.sqlite-wal
-*.sqlite-shm
-/scripts/benchmarks/
-
-# PR description screenshots belong on the pull request, not in the repository
-.screenshots/

.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "mantine": {
       "command": "npx",
-      "args": ["-y", "@mantine/mcp-server@9.6.0"]
+      "args": ["-y", "@mantine/mcp-server"]
     }
   }
-}
+}

.oxfmtrc.json

@@ -3,15 +3,5 @@
   "printWidth": 120,
   "endOfLine": "lf",
   "sortPackageJson": true,
-  "ignorePatterns": [
-    "**/*.cjs",
-    "**/lang/**",
-    "static-data/**",
-    "CHANGELOG.md",
-    "apps/docs/.docusaurus/**",
-    "apps/docs/build/**",
-    "apps/docs/blog/**",
-    "packages/custom-widgets/src/core/component-catalog.generated.json",
-    "apps/docs/static/custom-widgets/component-catalog-v1.json"
-  ]
+  "ignorePatterns": ["**/*.cjs", "**/lang/**", "static-data/**", "CHANGELOG.md", "apps/docs/.docusaurus/**", "apps/docs/build/**", "apps/docs/blog/**"]
 }

.oxlintrc.json

@@ -30,35 +30,7 @@
   "options": {
     "reportUnusedDisableDirectives": "off"
   },
-  "overrides": [
-    {
-      "files": ["apps/nextjs/src/**/*.ts", "apps/nextjs/src/**/*.tsx"],
-      "excludeFiles": ["**/*.spec.ts", "**/*.spec.tsx"],
-      "rules": {
-        "eslint/no-restricted-imports": [
-          "error",
-          {
-            "paths": [
-              {
-                "name": "@homarr/widgets",
-                "allowTypeImports": true,
-                "message": "Import a narrow @homarr/widgets export to preserve widget lazy loading."
-              }
-            ]
-          }
-        ]
-      }
-    }
-  ],
-  "ignorePatterns": [
-    "**/*.config.js",
-    "**/*.config.mjs",
-    "**/*.cjs",
-    "**/lang/*.d.json.ts",
-    ".next/**",
-    "apps/docs/.docusaurus/**",
-    "apps/docs/build/**"
-  ],
+  "ignorePatterns": ["**/*.config.js", "**/*.config.mjs", "**/*.cjs", "**/lang/*.d.json.ts", ".next/**", "apps/docs/.docusaurus/**", "apps/docs/build/**"],
   "settings": {
     "react": { "version": "19" }
   }