chore(ops): build with bun and ship v2's .output/standalone

v2 replaces pnpm with bun and moves the standalone build to apps/nextjs/.output/standalone, which already carries static assets, public and next.config.ts. Next still writes an incomplete .next/standalone, so the assembler now refuses to run without the v2 output rather than silently shipping that one. The notes now list v2's registration points, the tests that already fail on the upstream tag, and the one-way v1 to v2 database migration. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fix(definitions): declare how UniFi requests authenticate, as v2 requires
2026-10-08 00:49:44 +02:00 · 2026-10-08 00:46:25 +02:00 · 2026-10-08 00:24:57 +02:00 · 2026-10-08 00:24:57 +02:00 · 2026-10-08 00:24:57 +02:00 · 2026-10-08 00:24:57 +02:00
4156 changed files with 609309 additions and 167700 deletions
@@ -0,0 +1,40 @@
+---
+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.
+---
+
+# Homarr Codebase Context
+
+Orient from the current checkout before editing. Treat package manifests, exports, and source as authoritative when they differ from this snapshot.
+
+## Workflow
+
+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.
+
+## Current toolchain
+
+- Use Node `24.18.0` for application runtimes and Bun `1.4.2` for package management, pinned in `mise.toml` and `package.json`.
+- Use Bun workspaces with Turborepo and a shared hoisted install. 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.
+- `bun run dev` starts only `@homarr/nextjs`. Start a standalone runtime explicitly when the task needs it.
+
+## High-value seams
+
+- 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,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]/`
+
+Invoke `documentation-sync` only when users need new or corrected information to set up, use, or troubleshoot Homarr; follow the Documentation Sync criteria in `AGENTS.md`. When exposing tRPC through MCP, invoke `mcp-integration`.
@@ -0,0 +1,4 @@
+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."
@@ -0,0 +1,110 @@
+# 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`      | Next.js and Fumadocs 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                                  |
+
+`bun run dev` runs only `@homarr/nextjs`. Use `bun run --filter @homarr/tasks dev`, `bun run --filter @homarr/websocket dev`, or `bun run dev:docs` when a task needs those runtimes.
+
+In production, `apps/nextjs/src/instrumentation-node.ts` starts the tasks and WebSocket runtimes inside the Bun 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 SQLite and PostgreSQL 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`: Bun 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 `packages/db/schema/`. `DB_DRIVER` selects `better-sqlite3` or `node-postgres`; MySQL and MariaDB are no longer runtime drivers in v2. Existing MySQL installations must use the documented converter before upgrading. Migrations live under `packages/db/migrations/sqlite/` and `packages/db/migrations/postgresql/`.
+
+### 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 `bun run dev` for Next.js, `bun run dev:docs` for docs, and `bun run dev:cli -- <args>` for the Go developer CLI.
+- Use `bun run docker:dev:up` for the Redis development dependency.
+- Follow the Testing section in `AGENTS.md` for test creation and validation scope.
+- 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.
@@ -0,0 +1,85 @@
+# `@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`, `isRecord`, `hashObjectBase64`                                                                                        | Typed key/entry iteration, record guards, 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`, `formatBytes`, `formatBytesPair`, `formatByteRate`, `formatBitRate`, `defaultByteUnitSystem`, `metricToImperial`                     | Compact numbers, byte displays, byte/bit rates, and unit conversion    |
+| Byte types        | `ByteUnitSystem`, `FormatBytesOptions`, `FormatBitRateOptions`                                                                                       | Options for byte and bit-rate 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.
@@ -0,0 +1,57 @@
+---
+name: documentation-sync
+description: Write Homarr docs only when users need information to set up, use, or troubleshoot the app. Skip routine, obvious, or self-explanatory changes.
+---
+
+# Documentation Sync
+
+Apply the audience and scope rules in `AGENTS.md` first. Documentation exists only for information users need to set up, use, or troubleshoot Homarr. A code, UI, or API change alone does not warrant documentation; if a user does not need to know it, do not add it.
+
+For hidden capabilities such as the advanced widget feature, explain discovery, activation, and non-obvious behavior. For visible standard controls such as Delete, omit narration of what the label already conveys. Use the shortest explanation that preserves necessary technical detail; remove redundant prose in the passage being edited.
+
+When an update is warranted, inspect adjacent pages for structure and types, not as a verbosity target. The mappings below locate needed information; they do not require a page for every feature or code change.
+
+## Locate a needed update
+
+These are destinations for warranted updates, not triggers to add documentation:
+
+| 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         |
+
+If no existing row fits, search by the user-visible term and update the page where a user would look for the behavior:
+
+```bash
+rg -n "<term>" apps/docs/docs apps/docs/src
+```
+
+## Follow existing typed patterns
+
+For an integration:
+
+- 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.
+
+For a widget:
+
+- 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.
+- Explain only non-obvious option semantics, integration prerequisites, permission constraints, or behavior that the interface does not make clear.
+
+## Completion criteria
+
+1. Every passage adds information a user needs and cannot reasonably infer from the interface. Remove obvious, repetitive, or unnecessary prose.
+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 `bun run 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; run `bun run --filter @homarr/docs validate:links` after the static build.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Homarr Documentation Sync"
+  short_description: "Document only what users need to know"
+  default_prompt: "Use $documentation-sync only when users need new or corrected information to set up, use, or troubleshoot Homarr."
@@ -0,0 +1,58 @@
+---
+name: homarr-custom-widget
+description: Author, validate, preview, test, install, or configure API-backed Homarr Custom JSX v2 widgets.
+---
+
+# Homarr Custom Widget
+
+Author requested widgets with release context; validate, test, persist, and return artifacts.
+
+- Read primary API docs when missing/changed. Samples and successful previews are binding; load only needed schema, runtime,
+  security, or component context.
+- Batch unknown component searches/details. `contextAlreadyLoaded` reuses context; `phaseComplete` advances. Stop only for
+  genuine provider/model, lifecycle-service, or workbench-closure failure.
+- Community widgets use `customWidget_workshopSearch`, `customWidget_workshopGet`, and
+  `customWidget_workshopInstall`; configure and persist.
+
+Return one fenced `json` block with the complete definition; keep evidence prose outside it. The definition has keyed
+`sources`, `requests`, `template`, and optional `options`; actions are requests with `kind: "action"`.
+
+- `sources.default` is required. HTTP has `baseUrl`, `networkScope`, and credential-free `auth`; localhost/loopback requires
+  `networkScope: "loopback"`; never widen an explicit scope. Saved sources use `type: "integration"`/`integrationKind`;
+  Homarr holds credentials.
+- Saved integrations: discover kinds/full-access entries with `integration_getKinds`/`integration_all`, bind `integrationId`
+  before preview, omit URL/auth, and keep non-GET requests as actions.
+- Paths are slash-prefixed: strings use `{option:name}`/`{param:name}`; query/body uses `{"$option":"name"}`/`{"$param":"name"}`.
+  Loads use `trigger: "load"`; manual helpers use `trigger: "manual"`.
+- Actions stay manual; preserve `confirmation`, `permission`, and `invalidates`; DELETE requires full permission/confirmation.
+  `$param` is manual-only; `$option` may drive loads.
+- Load data.requestId/status.requestId with RefreshButton; status.requestId?.ok === false is error. Manual SubFetch never
+  populates data/status; its child receives (result, metadata) and renders its fields.
+- Options have `label`, `control`, `default`; installation config is `options.name`, never `inputs`. Request-bound TextInput,
+  Select, NumberInput, Pagination use literal `bind` + default and manual `SubFetch params` map `inputs.<name>` to `$param`.
+  Dependent pagination uses `defaultValue={1}`/`resetKey={inputs.query}`. Remove controls without an option/request/helper; guard arrays/nested with `??`;
+  preserve documented timezone values; use UTC only when the contract says UTC.
+- Templates are one expression: no imports, hooks, refs, raw HTML/events, browser requests, eval, recursion, IIFEs,
+  statement blocks, or arbitrary functions. Use registered component names; `Icon` may alias `TablerIcon`. Keep hierarchy,
+  theme tokens, useful states, and narrow/wide layouts purposeful.
+
+## Bounded lifecycle
+
+1. Build a credential-free definition from request, verified context, and sample. Preserve a migration's API path, method,
+   body, options, and behavior; omit unknown requests rather than guessing.
+2. Send the coherent complete definition directly to `customWidget_previewCreate`; it validates both manifest and JSX.
+   Use `customWidget_validateTemplate` only for isolated JSX diagnostics, never as a preview prerequisite. Use
+   `customWidget_previewReviseTemplate` for JSX-only corrections after a preview exists. In the Assistant wrapper, multiline
+   JSX uses `templateLines` and preview creation receives the complete definition.
+3. Test every returned query/simulated action once, batching independent queries. On a concrete schema/preview error, fix only
+   that field and retry `customWidget_previewCreate` with the corrected definition; use `customWidget_previewReviseTemplate`
+   only for JSX errors after a preview exists. Stop only for genuine provider/model, lifecycle-service, or
+   workbench-closure failure.
+4. If `previewCreate` used `definitionId`, persist with `customWidget_updateFromPreview`; otherwise use
+   `customWidget_createFromPreview`. Follow create `nextAction` once. Configure credentials in Homarr; never repeat plaintext
+   secrets.
+
+## Delivery
+
+Report actual lifecycle results. If unavailable, add one post-artifact `Unverified:` line naming missing validation, preview,
+renderer, or persistence. Never claim rendering/persistence from schema checks.
@@ -0,0 +1,4 @@
+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."
@@ -0,0 +1,37 @@
+# Runtime
+
+Load-query templates read `data.requestId` and `status.requestId`, plus `options.name` and temporary `inputs.name`. Manual `SubFetch` results stay local to that instance and never populate `data`/`status`; render them in its child callback. Status is `{ loading, ok, status, statusText, error }`. Render load queries directly from `data` and `status` with `RefreshButton`; never wrap them in `SubFetch`.
+
+`bind` is temporary; manual request values go in `params` and map to `$param`:
+
+```jsx
+<TextInput bind="search" label="Search" />
+<NumberInput bind="page" label="Page" defaultValue={1} resetKey={inputs.search} min={1} />
+<SubFetch requestId="search" trigger="manual" params={{ query: inputs.search ?? "", page: inputs.page ?? 1 }}>
+  {(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 ID, params, or definition changes, Homarr hides the prior result and returns to the trigger; new params fetch only after triggering again.
+
+Exact paths: load request ID `q` with raw preview body `B` -> `data.q === B`. `q=events` body`{"events":[...]}` -> `data.events.events`; do not flatten repeated keys. Manual `SubFetch` receives `B` as result -> `result.events`. Before persistence inspect core paths against preview; revise JSX and retest if mismatched
+
+Format timestamps with safe static helpers; never use `new Date`. Never invent a formatter component. Use `Date.toLocaleString(value, "en-US", documentedTimezone)` and label the documented timezone; if no timezone is documented, preserve the source value or omit any timezone label; use UTC only when the response contract says UTC. 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>
+```
+
+Request-bound controls use literal `bind` plus a default (`defaultChecked` for Switch/Checkbox); pass `inputs.<name>` through manual `SubFetch params` to matching `$param`. Options are installation config via `options.name`, never `inputs`; dependent pagination uses `defaultValue={1}`/`resetKey={inputs.query}`. Remove dead controls.
+
+Callback parameters must not shadow the reserved roots `data`, `status`, `options`, or `inputs`. Use registered component names returned by discovery; `Icon` is an accepted alias for canonical `TablerIcon`. 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.
@@ -0,0 +1,53 @@
+# 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;
+}
+```
+
+Key `default` is the required source ID, not a source property. Fields: `name?`, `baseUrl`, `networkScope`, `auth?`; localhost/loopback URLs require `networkScope: "loopback"`; never widen explicit scope:
+
+```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"]
+    }
+  }
+}
+```
+
+Saved sources use `{"type":"integration","integrationKind":"sonarr","integrationId":"saved-id"}`. Discover and bind a full-access entry before preview. Omit URL/auth; paths append to its URL, non-GET requests are actions, and exports omit `integrationId`.
+
+Auth is `none`, `bearer`, `basic`, `apiKeyHeader`, or `apiKeyQuery`. Requests default to source `default`, query/GET/load, inherited auth, and view permission. Use `load` for initial/current display and `manual` only for explicit interactions or invocation params. Actions are manual/modify; DELETE requires full permission and confirmation.
+
+JSON responses become their decoded value. Responses with `application/x-ndjson` become an array with one decoded object per non-empty line.
+
+Use real public API URLs and clear self-hosted placeholders. Homarr collects URL, scope, and credentials outside the manifest.
+
+Paths use `{option:name}`/`{param:name}`; query/body objects use `{"$option":"name"}`/`{"$param":"name"}`. `$param` is manual-only; `$option` may drive loads. Constants stay primitive.
+
+Every option has `label`, `control`, and `default`. Optional fields are `description`, `choices`, `choicesFrom`, `min`, `max`, `step`, `advanced`, and `group`.
@@ -0,0 +1,7 @@
+# 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.
@@ -0,0 +1,98 @@
+---
+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.
+---
+
+# 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.
+
+## Assess exposure
+
+Prefer:
+
+- 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()`:
+
+```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.
+  });
+```
+
+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",
+    },
+  })
+  .input(z.object({ id: z.string() }))
+  .mutation(async ({ ctx, input }) => {
+    // Perform the permission-scoped action.
+  });
+```
+
+## Write discoverable descriptions
+
+Include every item that applies:
+
+- 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.
+
+Use precise domain language. A description such as `Get calendar events` is insufficient because it omits supported services, required IDs, and result scope.
+
+## Shape inputs for clients
+
+- 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.
+
+## Register the eager router
+
+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`:
+
+```typescript
+import { resourceRouter } from "./router/resource";
+
+export const mcpRouter = createTRPCRouter({
+  resource: resourceRouter,
+});
+```
+
+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.
+
+## Validate the tool surface
+
+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. When validating tool-list or extraction changes, use the focused API MCP spec: `bun run test packages/api/src/test/mcp.spec.ts`.
+5. When validating protocol or transport changes, use the focused route spec: `bun run 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.
@@ -0,0 +1,4 @@
+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."
@@ -0,0 +1 @@
+../.agents/skills
@@ -1,11 +0,0 @@
-version = 1
-
-[[analyzers]]
-name = "javascript"
-
-  [analyzers.meta]
-  plugins = ["react"]
-  environment = ["nodejs"]
-
-[[transformers]]
-name = "prettier"
@@ -5,7 +5,35 @@ node_modules
 npm-debug.log
 README.md
 .next
+**/.output
+.turbo
+**/.turbo
+**/next-env.d.ts
+packages/db/migrations/*/migrate.cjs
+packages/cli/cli.cjs
+apps/tasks/tasks.cjs
+apps/tasks/tasks.css
+apps/websocket/wssServer.cjs
+apps/websocket/wssServer.css
+.bun-cache
+**/.bun-cache
+coverage
+**/coverage
+**/.docusaurus
+**/build
 .git
+.github
 dev
 .build
-e2e
+e2e
+apps/docs/*
+!apps/docs/package.json
+apps/nextjs/.next
+.env
+.env.*
+!.env.example
+
+benchmark-results
+scripts/benchmarks/results
+**/__pycache__
+**/*.tsbuildinfo
@@ -1,38 +1,25 @@
 # Since .env is gitignored, you can use .env.example to build a new `.env` file when you clone the repo.
-# Keep this file up-to-date when you add new variables to \`.env\`.
+# Keep this file up-to-date when you add new variables to `.env`.

 # This file will be committed to version control, so make sure not to have any secrets in it.
 # If you are cloning this repo, create a copy of this file named `.env` and populate it with your secrets.

-# The below secret is not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used)
-AUTH_SECRET="supersecret"
+# Generate two different 64-character hex values with `openssl rand -hex 32` before starting Homarr.
+# Never reuse these values or commit the populated `.env` file.
+AUTH_SECRET=

 # The below secret is used to encrypt integration secrets in the database.
-# It should be a 32-byte string, generated by running `openssl rand -hex 32` on Unix
-# or starting the project without any (which will show a randomly generated one).
-SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
-
-# Cron job API key is generated every time the container starts as it is required for communication between nextjs-api and tasks-api
-# export CRON_JOB_API_KEY=$(openssl rand -base64 32)
-# CRON_JOB_API_KEY="your-generated-api-key"
+# Homarr will reject an empty or invalid value and print a randomly generated candidate.
+SECRET_ENCRYPTION_KEY=

 LOG_LEVEL='info'

 # This is how you can use the sqlite driver:
 DB_DRIVER='better-sqlite3'
-DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'
-
-# Those are the two ways to use the mysql2 driver:
-# 1. Using the URL format:
-# DB_DRIVER='mysql2'
-# DB_URL='mysql://user:password@host:port/database'
-# 2. Using the connection options format:
-# DB_DRIVER='mysql2'
-# DB_HOST='localhost'
-# DB_PORT='3306'
-# DB_USER='username'
-# DB_PASSWORD='password'
-# DB_NAME='name-of-database'
+# Set an absolute writable SQLite path so migrations and the app use the same file.
+# Their working directories differ; do not use a relative path here.
+# Container images use /appdata/db/db.sqlite by default instead.
+DB_URL=

 # The following is an example on how to use the node-postgres driver:
 # DB_DRIVER='node-postgres'
@@ -45,8 +32,53 @@ DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'

 TURBO_TELEMETRY_DISABLED=1

+# Turborepo remote cache (optional, for faster CI/local builds)
+# Uncomment and fill in to enable remote caching locally.
+# CI uses GitHub secrets for these values automatically.
+# TURBO_API=https://your-cache-worker.workers.dev
+# TURBO_TEAM=team_your_team
+# TURBO_TOKEN=your-turbo-token
+# TURBO_REMOTE_CACHE_SIGNATURE_KEY=your-signature-key
+
+# Comma-separated paths to Docker-compatible Unix sockets.
+# Useful for connecting to multiple runtimes (Docker + Podman) simultaneously.
+# When unset and no TCP hosts configured, defaults to /var/run/docker.sock.
+# Example: DOCKER_SOCKET_PATHS=/var/run/docker.sock,/run/user/1000/podman/podman.sock
+# DOCKER_SOCKET_PATHS=
+
 # Enable kubernetes tool
 # ENABLE_KUBERNETES=true

 # Enable mock integration
-UNSAFE_ENABLE_MOCK_INTEGRATION=true
+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.
+# Public Homarr origin used by MCP OAuth metadata and redirects behind proxies.
+# BASE_URL=https://homarr.example.com
+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; Assistant conversation history remains writable for canned chats.
+# Set to false for writable preview deployments so the demo user can modify the dashboard.
+# DEMO_READ_ONLY=false
@@ -25,6 +25,18 @@ body:
    attributes:
      label: Additional information
      description: Add any other information related to the bug here, screenshots if applicable.
+  - type: input
+    id: exactBuild
+    attributes:
+      label: Exact build or image
+      description: For preview or development builds, include the commit SHA or image digest. A moving tag such as v2 is not enough to identify the build.
+      placeholder: "Commit SHA, image digest, or release version"
+  - type: input
+    id: lastWorkingVersion
+    attributes:
+      label: Last working version
+      description: If this worked before, include the last version or build where you tried the same action. Leave blank if unknown.
+      placeholder: "Version or commit SHA"
  - type: dropdown
    id: version
    attributes:
@@ -33,6 +45,59 @@ body:
      options:
        # The below comment is used to insert a new version with on-release.yml
        #NEXT_VERSION#
+        - 2.2.0
+        - 2.1.2
+        - 2.0.0
+        - 1.77.0
+        - 1.76.2
+        - 1.76.1
+        - 1.76.0
+        - 1.75.0
+        - 1.74.0
+        - 1.73.0
+        - 1.72.0
+        - 1.71.0
+        - 1.70.0
+        - 1.69.2
+        - 1.69.0
+        - 1.68.0
+        - 1.67.0
+        - 1.66.1
+        - 1.66.0
+        - 1.65.0
+        - 1.64.0
+        - 1.62.0
+        - 1.61.0
+        - 1.60.1-beta.1
+        - 1.60.0
+        - 1.59.3
+        - 1.59.2
+        - 1.59.1
+        - 1.59.0
+        - 1.58.1
+        - 1.58.0
+        - 1.57.1
+        - 1.57.0
+        - 1.56.1
+        - 1.56.0
+        - 1.55.0
+        - 1.54.0
+        - 1.53.0
+        - 1.52.0
+        - 1.51.0
+        - 1.50.1
+        - 1.50.0
+        - 1.49.1
+        - 1.49.0
+        - 1.48.0
+        - 1.47.0
+        - 1.46.0
+        - 1.45.3
+        - 1.45.2
+        - 1.45.1
+        - 1.45.0
+        - 1.44.0
+        - 1.43.1
        - 1.43.0
        - 1.42.1
        - 1.42.0
@@ -0,0 +1,48 @@
+name: 🐞 Custom Widget bug
+description: Report a problem with a Custom JSX widget, its requests, preview, or editor
+title: "bug: custom widget "
+labels: ["needs triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Share a small reproduction so we can distinguish widget code, upstream API, and Homarr problems.
+        Remove API keys, passwords, tokens, cookies, authorization headers, private URLs, and personal data from everything you share, including exports and screenshots. Replace private hosts with `https://example.invalid` while preserving relevant paths and response structure.
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Actual and expected behavior
+      description: Describe what happens and what you expected. Include the exact error text and a sanitized screenshot if useful.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Include the affected request or control, relevant widget options, and whether this occurs in Test, preview, or on the dashboard. For layout issues, include the widget size and desktop or mobile viewport.
+    validations:
+      required: true
+  - type: textarea
+    id: definition
+    attributes:
+      label: Sanitized widget definition
+      description: Paste or attach the exported JSON with sources, requests, options, and JSX template. Prefer the smallest definition that reproduces the problem. If export fails, include the relevant JSX and request configuration. Check for private URLs and sensitive data before sharing.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the exact Homarr release, commit SHA, or image digest; installation method; browser/version; and desktop or mobile OS. For request issues, include the source type (HTTP or integration), integration kind, and upstream service version. Do not include server URLs or credentials.
+      placeholder: |
+        Homarr version / commit / image digest:
+        Installation method:
+        Browser and OS:
+        Source type, integration kind, and service version:
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Sanitized API response and logs
+      description: For request or data issues, include the request ID, method, relative API path, HTTP status, and a small response sample preserving field names and types. Add relevant Homarr or browser console errors. Remove sensitive values and private URLs; leave blank for purely visual issues.
@@ -25,16 +25,16 @@ body:
      label: Public API available?
      description: Is there a public API available, that we can consume in Homarr?
      options:
-        - Yes, available on a website
-        - Yes, available in the application itself
-        - No
+        - "Yes, available on a website"
+        - "Yes, available in the application itself"
+        - "No"
    validations:
      required: true
  - type: dropdown
    attributes:
      label: Are you willing to contribute this yourself?
      options:
-      - Yes
-      - No
+        - "Yes"
+        - "No"
    validations:
      required: true
@@ -24,7 +24,7 @@ body:
    attributes:
      label: Are you willing to contribute this yourself?
      options:
-        - Yes
-        - No
+        - "Yes"
+        - "No"
    validations:
      required: true
@@ -0,0 +1,2 @@
+.secrets
+!.secrets.example
@@ -0,0 +1,4 @@
+TURBO_API=
+TURBO_TEAM=
+TURBO_TOKEN=
+TURBO_REMOTE_CACHE_SIGNATURE_KEY=
@@ -0,0 +1,38 @@
+# Running CI locally
+
+Install [Act](https://nektosact.com/installation/index.html) and ensure Docker is running, then use:
+
+```bash
+bun run ci:act:fast
+bun run ci:act:docker
+bun run ci:act:all
+bun run ci:act:cleanup
+```
+
+`fast` runs the database checks and quality gate and requires an `origin/dev` tracking ref. `docker` and `all` use the manual validation event to run those checks, build the container once, and run the converter boot/restart smoke test. `cleanup` validates the manual cleanup path without calling GitHub. The wrapper supports regular clones and Git worktrees, including non-default Docker contexts. Linux dependencies are kept in Docker volumes instead of overwriting host `node_modules`. The first run downloads the Act runner and Playwright browser dependencies.
+
+For rootless Docker, set `ACT_TESTCONTAINERS_HOST` to a host address reachable from the runner when loopback callbacks are unavailable.
+
+Remote caching is optional locally. Copy `.github/act/.secrets.example` to `.github/act/.secrets`, populate it with rotated credentials, and run with:
+
+```bash
+ACT_SECRET_FILE=.github/act/.secrets bun run ci:act:all
+```
+
+Act never publishes or deletes GHCR images. The secret file is ignored by Git.
+
+## PR preview images
+
+Successful non-draft pull requests from this repository publish an amd64 image:
+
+```bash
+docker pull ghcr.io/homarr-labs/homarr-test:pr-<number>
+```
+
+The tag is replaced when the pull request is updated and deleted when it closes. Production Homarr images remain the supported multi-architecture releases. The `homarr-test` package must be configured as public in GHCR for unauthenticated testers.
+
+## Dokploy preview cache
+
+Keep `needs-demo` as the Dokploy preview label. Under the application's **Preview Build-time Secrets**, configure `TURBO_API`, `TURBO_TEAM`, `TURBO_TOKEN`, and `TURBO_REMOTE_CACHE_SIGNATURE_KEY`. Dokploy passes these to the Dockerfile as BuildKit secrets. Do not configure the token or signature key as Docker build arguments.
+
+Rotate any credentials that have appeared in chat, logs, or committed configuration before enabling the cache.
@@ -0,0 +1,57 @@
+name: Extract Build Artifact
+description: Extracts artifacts from an existing Docker image to be used for from source installation
+inputs:
+  digest:
+    description: Digest of Docker image to use
+    required: true
+  architecture:
+    description: Name of architecture, will be used to build artifact content (amd64 or arm64)
+    required: true
+  release-tag:
+    description: Tag of the release to which the artifact will be attached
+    required: true
+  repository:
+    description: Repository to which the release belongs, e.g. owner/repo
+    required: true
+  token:
+    description: GitHub token with permissions to upload release assets
+    required: true
+runs:
+  using: "composite"
+  steps:
+    - name: Start docker container for ${{ inputs.architecture }}
+      run: |
+        docker run --name homarr \
+          -e "SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000" \
+          --detach --rm ${{ inputs.digest }}
+      shell: bash
+    - name: Prepare extraction
+      run: |
+        docker exec homarr cp /etc/nginx/templates/nginx.conf /app && \
+        mkdir -p ${{ runner.temp }}/extraction/${{ inputs.architecture }}
+      shell: bash
+    - name: Extract source from ${{ inputs.architecture }} container (alpine)
+      run: |
+        docker exec homarr tar -czf extraction-alpine.tar.gz -C /app . && \
+        docker cp homarr:/app/extraction-alpine.tar.gz ${{ runner.temp }}/extraction/${{ inputs.architecture }}/build-alpine-${{ inputs.architecture }}.tar.gz && \
+        docker exec homarr rm /app/extraction-alpine.tar.gz
+      shell: bash
+    - name: Extract source from ${{ inputs.architecture }} container (debian)
+      run: |
+        docker exec homarr tar -czf extraction-debian.tar.gz -C /app . && \
+        docker cp homarr:/app/extraction-debian.tar.gz ${{ runner.temp }}/extraction/${{ inputs.architecture }}/build-debian-${{ inputs.architecture }}.tar.gz
+      shell: bash
+    - name: Stop ${{ inputs.architecture }} container
+      if: always()
+      run: docker container remove --force --volumes homarr
+      shell: bash
+    - name: Add build archive to release (alpine)
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: gh release upload --repo ${{ inputs.repository }} ${{ inputs.release-tag }} ${{ runner.temp }}/extraction/${{ inputs.architecture }}/build-alpine-${{ inputs.architecture }}.tar.gz --clobber
+      shell: bash
+    - name: Add build archive to release (debian)
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: gh release upload --repo ${{ inputs.repository }} ${{ inputs.release-tag }} ${{ runner.temp }}/extraction/${{ inputs.architecture }}/build-debian-${{ inputs.architecture }}.tar.gz --clobber
+      shell: bash
@@ -0,0 +1,39 @@
+name: Prebuilt dependencies for debian
+description: Provides prebuilt dependencies for debian based docker images
+inputs:
+  architecture:
+    description: Name of architecture, will be used to build docker image (e.g. amd64, arm64)
+    required: true
+outputs:
+  path:
+    description: Path to extracted prebuilt dependencies
+    value: ${{ runner.temp }}/prebuilts
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v4
+
+    - name: Build docker image for ${{ inputs.architecture }}
+      id: build
+      uses: docker/build-push-action@v7
+      with:
+        push: false
+        load: true
+        context: ./deployments/prebuilt-debian
+        platforms: linux/${{ inputs.architecture }}
+        tags: prebuilt-debian
+    - name: Start docker container for ${{ inputs.architecture }}
+      run: |
+        docker run --name prebuilt-debian \
+          --detach --rm prebuilt-debian
+      shell: bash
+    - name: Extract prebuilt dependencies from ${{ inputs.architecture }} container
+      run: |
+        mkdir -p ${{ runner.temp }}/prebuilts && \
+        docker cp prebuilt-debian:/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node ${{ runner.temp }}/prebuilts/better_sqlite3.node
+      shell: bash
+    - name: Stop ${{ inputs.architecture }} container
+      if: always()
+      run: docker container remove --force --volumes prebuilt-debian
+      shell: bash
@@ -4,10 +4,18 @@
  <h3>Homarr</h3>
 </div>

-**Thank you for your contribution. Please ensure that your pull request meets the following pull request:**
+**Thank you for your contribution. Please ensure that your pull request meets the following requirements:**

- [ ] Builds without warnings or errors (`pnpm build`, autofix with `pnpm format:fix`)
- [ ] Pull request targets `dev` branch
+- [ ] Relevant checks pass without warnings or errors
+- [ ] Pull request targets the intended base branch (`dev` by default; `release/v2` for v2 release work)
 - [ ] Commits follow the [conventional commits guideline](https://www.conventionalcommits.org/en/v1.0.0/)
- [ ] No shorthand variable names are used (eg. `x`, `y`, `i` or any abbrevation)
- [ ] Documentation is up to date. Create a pull request [here](https://github.com/homarr-labs/documentation/).
+- [ ] No shorthand variable names are used (for example, `x`, `y`, `i`, or abbreviations)
+- [ ] Documentation under `apps/docs` is updated only when users need new or corrected information to use the app
+- [ ] When using AI, no temporary files are checked in and the code style follows the rest of the project
+
+**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)
+- [ ] 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)
@@ -1,26 +1,41 @@
 {
  $schema: "https://docs.renovatebot.com/renovate-schema.json",
-  extends: ["config:recommended"],
+  extends: ["config:recommended", ":dependencyDashboardApproval"],
  packageRules: [
    {
      matchPackageNames: ["^@homarr/"],
      enabled: false,
    },
-    // Reenable once https://github.com/privatenumber/tsx/issues/737 is fixed
+    // Reenable once bug with undici v8 is fixed (https://github.com/homarr-labs/homarr/issues/5467)
    {
-      matchPackageNames: ["tsx"],
+      matchPackageNames: ["undici"],
+      matchNewValue: "8.*",
      enabled: false,
    },
    {
      matchUpdateTypes: ["minor", "patch", "pin", "digest"],
      automerge: true,
    },
+    {
+      // disallow automerge for trustedDependencies (native builds need manual verification)
+      matchPackageNames: [
+        "@tree-sitter-grammars/tree-sitter-yaml",
+        "bcrypt",
+        "cpu-features",
+        "esbuild",
+        "sharp",
+        "ssh2",
+        "tree-sitter",
+        "tree-sitter-json",
+      ],
+      automerge: false,
+    },
  ],
  updateInternalDeps: true,
  rangeStrategy: "bump",
  automerge: false,
-  baseBranches: ["dev"],
-  dependencyDashboard: false,
+  baseBranchPatterns: ["dev"],
+  dependencyDashboard: true,
  // prevent special characters in branch names (otherwise git errors occur on windows)
  branchNameStrict: true,
 }
@@ -0,0 +1,35 @@
+name: Formatting
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: ["**"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  format:
+    name: Check formatting
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup
+        uses: ./tooling/github/setup
+
+      - name: Check changed files
+        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 bun x oxfmt --check --no-error-on-unmatched-pattern --
@@ -1,29 +0,0 @@
-name: "[Dependency Updates] Auto Approve"
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-permissions: {}
-
-jobs:
-  approve-automatic-prs:
-    runs-on: ubuntu-latest
-    if: github.actor_id == 158783068 || github.actor_id == 190541745 || github.actor_id == 210161987 # Id of renovate bot and crowdin bot see https://api.github.com/users/homarr-renovate%5Bbot%5D and https://api.github.com/users/homarr-crowdin%5Bbot%5D and https://api.github.com/users/homarr-update-contributors%5Bbot%5D
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v5
-      - name: Obtain token
-        id: obtainToken
-        uses: actions/create-github-app-token@v2
-        with:
-          private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          app-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
-          permission-pull-requests: write # required to approve pull request
-
-      - name: Install GitHub CLI
-        run: sudo apt-get install -y gh
-      - name: Approve automatic PRs
-        env:
-          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
-        run: |
-          gh pr review ${{github.event.pull_request.number}} --approve --body "Automatically approved by GitHub Action"
@@ -0,0 +1,43 @@
+name: "[Bots] Reconcile Auto-merge"
+
+on:
+  schedule:
+    - cron: "*/30 * * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  reconcile:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Obtain token
+        id: obtainToken
+        uses: actions/create-github-app-token@v3
+        with:
+          private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
+          permission-pull-requests: write # required to enable auto-merge
+
+      - name: Install GitHub CLI
+        run: sudo apt-get install -y gh
+
+      - name: Re-enable auto-merge for prepared bot PRs
+        env:
+          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
+        run: |
+          # 158783068: homarr-renovate[bot]
+          # 190541745: homarr-crowdin[bot]
+          # 210161987: homarr-update-contributors[bot]
+          # 175441: homarr-releases[bot]
+          gh pr list --repo "${{ github.repository }}" --base dev --state open --limit 100 \
+            --json number,author,reviewDecision,mergeStateStatus,autoMergeRequest \
+            --jq '.[] | select(.author.login as $login | ["app/homarr-renovate", "app/homarr-crowdin", "app/homarr-update-contributors", "app/homarr-releases"] | index($login)) | select(.reviewDecision == "APPROVED") | select(.mergeStateStatus == "CLEAN") | select(.autoMergeRequest == null) | .number' \
+          | while read -r pr; do
+              echo "Re-enabling auto-merge on PR #$pr"
+              gh pr merge "$pr" --auto --squash
+            done
@@ -0,0 +1,47 @@
+name: "[Bots] Approve and Auto-merge"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions: {}
+
+jobs:
+  approve-and-automerge:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # 158783068: homarr-renovate[bot]
+    # 190541745: homarr-crowdin[bot]
+    # 210161987: homarr-update-contributors[bot]
+    # 175441: homarr-releases[bot]
+    # Extracted from https://api.github.com/users/<username>
+    if: |
+      (github.actor_id == 158783068 || github.actor_id == 190541745 || github.actor_id == 210161987 || github.actor_id == 175441) &&
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.event.pull_request.base.ref == 'dev'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Obtain token
+        id: obtainToken
+        uses: actions/create-github-app-token@v3
+        with:
+          private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
+          permission-pull-requests: write # required to approve a pull request and enable auto-merge
+
+      - name: Install GitHub CLI
+        run: sudo apt-get install -y gh
+
+      - name: Approve and enable auto-merge
+        env:
+          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
+        run: |
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          if [ "$(gh pr view "$PR_NUMBER" --json reviewDecision --jq .reviewDecision)" != "APPROVED" ]; then
+            gh pr review "$PR_NUMBER" --approve --body "Automatically approved by Homarr bot policy"
+          fi
+          if [ "$(gh pr view "$PR_NUMBER" --json autoMergeRequest --jq '.autoMergeRequest != null')" != "true" ]; then
+            gh pr merge "$PR_NUMBER" --auto --squash
+          fi
@@ -0,0 +1,463 @@
+name: CI
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: ["**"]
+  pull_request_target:
+    types: [closed]
+    branches: ["**"]
+  push:
+    branches: [main, dev, beta, next, v2, release/v2]
+  merge_group:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      operation:
+        description: Operation to run
+        required: true
+        default: validate
+        type: choice
+        options:
+          - validate
+          - publish
+          - cleanup
+      pr_number:
+        description: PR number for publish or cleanup
+        required: false
+        type: number
+      ref:
+        description: Git ref to validate or publish
+        required: false
+        type: string
+
+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' }}
+
+env:
+  FORCE_COLOR: 3
+  SKIP_ENV_VALIDATION: true
+  TURBO_TELEMETRY_DISABLED: 1
+  REGISTRY: ghcr.io
+  PREVIEW_IMAGE: ghcr.io/homarr-labs/homarr-test
+
+jobs:
+  database-validation:
+    name: Database validation
+    if: github.event_name != 'pull_request_target' && (github.event_name != 'release' || startsWith(github.event.release.tag_name, 'v2.')) && (github.event_name != 'workflow_dispatch' || inputs.operation != 'cleanup')
+    uses: ./.github/workflows/database.yml
+
+  fast-gate:
+    name: Fast gate
+    needs: database-validation
+    if: ${{ !cancelled() && github.event_name != 'pull_request_target' && (github.event_name != 'release' || startsWith(github.event.release.tag_name, 'v2.')) && (github.event_name != 'workflow_dispatch' || inputs.operation != 'cleanup') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      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 }}
+      TURBO_SCM_BASE: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before || 'HEAD~1' }}
+      TURBO_SCM_HEAD: ${{ github.sha }}
+    steps:
+      - name: Require database validation
+        env:
+          DATABASE_RESULT: ${{ needs.database-validation.result }}
+        run: test "$DATABASE_RESULT" = success
+
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || '' }}
+
+      - name: Validate manual inputs
+        if: github.event_name == 'workflow_dispatch' && inputs.operation == 'publish'
+        env:
+          PR_NUMBER: ${{ inputs.pr_number }}
+          BUILD_REF: ${{ inputs.ref }}
+        run: |
+          test -n "$PR_NUMBER" || { echo "pr_number is required for publish"; exit 1; }
+          test -n "$BUILD_REF" || { echo "ref is required for publish"; exit 1; }
+
+      - name: Setup
+        uses: ./tooling/github/setup
+        with:
+          next-cache: "all"
+          turbo-cache: "true"
+
+      - name: Copy environment defaults
+        run: cp .env.example .env
+
+      - name: Lint, typecheck, and build workspaces
+        run: |
+          scope=(--affected)
+          if [[ "$GITHUB_EVENT_NAME" == "workflow_dispatch" ]]; then
+            scope=()
+          fi
+          bun run turbo run lint typecheck build "${scope[@]}" --continue=dependencies-successful --concurrency=2
+
+      - name: Validate workspace configuration
+        run: bun run lint:ws
+
+      - name: Validate Custom Widget architecture
+        run: bun run check:custom-widgets
+
+      - name: Validate checked-in OpenAPI schema
+        run: bun run check:openapi
+
+      - name: Validate Custom Widget bundle budget
+        run: |
+          bun run turbo run build --filter=@homarr/nextjs
+          bun run check:custom-widget-bundle
+
+  container:
+    name: Container and migration smoke
+    # Legacy converter verification is opt-in, not a release publication gate.
+    needs: [fast-gate, preview-amd64]
+    if: |
+      !cancelled() && needs.fast-gate.result == 'success' &&
+      github.event_name == 'workflow_dispatch' && inputs.operation == 'validate'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || '' }}
+
+      - name: Setup
+        uses: ./tooling/github/setup
+
+      - 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-e2e
+
+      - name: Set up Docker Buildx
+        if: needs.preview-amd64.outputs.digest == '' && !env.ACT
+        uses: docker/setup-buildx-action@v4
+
+      - name: Build container once
+        if: needs.preview-amd64.outputs.digest == '' && !env.ACT
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          network: host
+          platforms: linux/amd64
+          load: true
+          push: false
+          tags: |
+            homarr-ci
+            homarr-e2e
+          labels: |
+            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
+          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 }}
+
+      - name: Build container once with Act
+        if: env.ACT
+        env:
+          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 }}
+        run: |
+          bash tooling/github/docker-build.sh --platform linux/amd64 \
+            --tag homarr-ci --tag homarr-e2e .
+
+      - name: Cache Playwright browsers
+        if: "!env.ACT"
+        id: playwright-cache
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+
+      - name: Install Playwright Chromium
+        if: steps.playwright-cache.outputs.cache-hit != 'true' || env.ACT
+        run: bun x playwright install --with-deps chromium
+
+      - name: Install Playwright system deps
+        if: steps.playwright-cache.outputs.cache-hit == 'true'
+        run: bun x playwright install-deps chromium
+
+      - name: Install standalone converter test dependencies
+        run: bun install --cwd tools/mysql-to-sqlite --frozen-lockfile
+
+      - name: Verify converted database boots and survives restart
+        env:
+          NODE_ENV: development
+          CI: "true"
+        run: bun x vitest run --project e2e e2e/mysql-conversion.spec.ts --maxWorkers 1
+
+      - name: Upload E2E artifacts
+        if: failure() && !env.ACT
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-report
+          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: [fast-gate, preview-amd64, preview-arm64]
+    if: |
+      !cancelled() &&
+      needs.fast-gate.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
+        env:
+          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        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}.`);
+            }
+
+      - name: Publish preview manifest
+        if: "!env.ACT"
+        env:
+          AMD64_DIGEST: ${{ needs.preview-amd64.outputs.digest }}
+          ARM64_DIGEST: ${{ needs.preview-arm64.outputs.digest }}
+        run: |
+          tags=(-t "${PREVIEW_IMAGE}:${PREVIEW_TAG}")
+          docker buildx imagetools create "${tags[@]}" \
+            "${PREVIEW_IMAGE}@${AMD64_DIGEST}" \
+            "${PREVIEW_IMAGE}@${ARM64_DIGEST}"
+
+      - 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
+
+  cleanup:
+    name: Clean up preview image
+    if: github.event_name == 'pull_request_target' || (github.event_name == 'workflow_dispatch' && inputs.operation == 'cleanup')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      packages: write
+    env:
+      IMAGE_TAG: pr-${{ github.event.pull_request.number || inputs.pr_number }}
+    steps:
+      - name: Validate cleanup input
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          PR_NUMBER: ${{ inputs.pr_number }}
+        run: test -n "$PR_NUMBER" || { echo "pr_number is required for cleanup"; exit 1; }
+
+      - name: Delete GHCR package version
+        if: "!env.ACT"
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const packageName = "homarr-test";
+            const org = context.repo.owner;
+            const tag = process.env.IMAGE_TAG;
+            const versions = await github.paginate(
+              github.rest.packages.getAllPackageVersionsForPackageOwnedByOrg,
+              { package_type: "container", package_name: packageName, org, per_page: 100 },
+            );
+            const target = versions.find((version) =>
+              version.metadata?.container?.tags?.includes(tag),
+            );
+            if (!target) {
+              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,
+              org,
+              package_version_id: target.id,
+            });
+            core.info(`Deleted package version ${target.id} (${tag})`);
+
+      - name: Show Act cleanup result
+        if: env.ACT
+        run: echo "Act validated cleanup for ${IMAGE_TAG}; external GHCR writes are disabled locally."
@@ -1,110 +0,0 @@
-name: "[Quality] Code Analysis"
-
-on:
-  pull_request:
-    branches: ["*"]
-  push:
-    branches: ["main"]
-  merge_group:
-
-concurrency:
-  group: "${{ github.workflow }}-${{ github.ref }}"
-  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
-
-# You can leverage Vercel Remote Caching with Turbo to speed up your builds
-# @link https://turborepo.org/docs/core-concepts/remote-caching#remote-caching-on-vercel-builds
-env:
-  FORCE_COLOR: 3
-  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-
-      - name: Setup
-        uses: ./tooling/github/setup
-
-      - name: Copy env
-        shell: bash
-        run: cp .env.example .env
-
-      - name: Lint
-        run: pnpm lint && pnpm lint:ws
-
-  format:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-
-      - name: Setup
-        uses: ./tooling/github/setup
-
-      - name: Format
-        run: pnpm format
-
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-
-      - name: Setup
-        uses: ./tooling/github/setup
-
-      - name: Typecheck
-        run: turbo typecheck
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-
-      - name: Setup
-        uses: ./tooling/github/setup
-
-      - name: Test
-        run: pnpm test
-
-      - name: "Report Coverage"
-        # Set if: always() to also generate the report if tests are failing
-        # Only works if you set `reportOnFailure: true` in your vite config as specified above
-        if: always()
-        uses: davelosert/vitest-coverage-report-action@v2
-
-  e2e:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v5
-      - name: Setup
-        uses: ./tooling/github/setup
-      - name: Build docker image
-        id: build-docker-image
-        uses: docker/build-push-action@v6
-        with:
-          platforms: linux/amd64
-          context: .
-          push: false
-          tags: homarr-e2e
-          network: host
-        env:
-          SKIP_ENV_VALIDATION: true
-      - name: Install playwright browsers
-        run: pnpm exec playwright install chromium
-      - name: Run E2E Tests
-        shell: bash
-        run: pnpm test:e2e
-
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - name: Setup
-        uses: ./tooling/github/setup
-      - name: Copy env
-        shell: bash
-        run: cp .env.example .env
-      - name: Build
-        run: pnpm build
@@ -13,7 +13,8 @@ permissions:
 jobs:
  validate-pull-request-title:
    runs-on: ubuntu-latest
+    timeout-minutes: 1
    steps:
      - uses: amannn/action-semantic-pull-request@v6
        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -10,18 +10,19 @@ permissions:

 jobs:
  download-crowdin-translations:
+    timeout-minutes: 5
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7

      - name: Obtain token
        id: obtainToken
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.CROWDIN_APP_PRIVATE_KEY }}
-          app-id: ${{ secrets.CROWDIN_APP_ID }}
+          client-id: ${{ vars.CROWDIN_CLIENT_ID }}
          permission-contents: write # required to commit to crowdin branch
          permission-pull-requests: write # required to create pull request

@@ -1,4 +1,6 @@
 name: "[Crowdin] Upload translations"
+permissions:
+  contents: read

 on:
  workflow_dispatch:
@@ -12,10 +14,11 @@ jobs:
    # Don't run this action if the downloaded translations are being pushed
    if: "!contains(github.event.head_commit.message, 'chore(lang)')"
    runs-on: ubuntu-latest
+    timeout-minutes: 5

    steps:
      - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7

      - name: Upload Crowdin translations
        uses: crowdin/github-action@v2
@@ -0,0 +1,103 @@
+name: Database migrations
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  NODE_ENV: development
+  CI: "true"
+  SKIP_ENV_VALIDATION: "true"
+  TURBO_TELEMETRY_DISABLED: "1"
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      migrations: ${{ steps.select.outputs.migrations }}
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Select database checks
+        id: select
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
+        shell: bash
+        run: |
+          migrations=false
+          if [[ "$EVENT_NAME" != pull_request && "$EVENT_NAME" != merge_group && "$EVENT_NAME" != push ]] ||
+             [[ -z "$BASE_SHA" || "$BASE_SHA" =~ ^0+$ ]] ||
+             ! git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null; then
+            migrations=true
+          else
+            changed_files=$(mktemp)
+            trap 'rm -f "$changed_files"' EXIT
+            comparison="$BASE_SHA...HEAD"
+            if [[ "$EVENT_NAME" = push ]]; then comparison="$BASE_SHA..HEAD"; fi
+            git diff --name-only -z "$comparison" > "$changed_files"
+            while IFS= read -r -d '' file; do
+              case "$file" in
+                packages/db/*|packages/core/src/infrastructure/db/*|packages/core/src/infrastructure/certificates/*|packages/auth/*|packages/api/src/router/onboard*|packages/api/src/router/test/onboard*|packages/onboarding/*|apps/nextjs/src/app/api/backup/*|apps/nextjs/src/app/*/init/*|Dockerfile|scripts/run.sh|scripts/entrypoint.sh|deployments/*|package.json|packages/core/package.json|packages/common/package.json|packages/definitions/package.json|packages/server-settings/package.json|packages/validation/package.json|mise.toml|bun.lock|bunfig.toml|patches/*|vitest*|tooling/github/*|.github/workflows/database.yml|.github/workflows/ci.yml)
+                  migrations=true
+                  ;;
+              esac
+            done < "$changed_files"
+          fi
+          echo "migrations=$migrations" >> "$GITHUB_OUTPUT"
+
+  journals:
+    name: Migration journals
+    needs: changes
+    if: needs.changes.outputs.migrations == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+      - uses: ./tooling/github/setup
+      - run: bun x vitest run --project db-node packages/db/test/migration-journal.spec.ts
+
+  migrations:
+    name: SQLite and PostgreSQL migrations
+    needs: changes
+    if: needs.changes.outputs.migrations == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+      - uses: ./tooling/github/setup
+      - name: Reject retired database configuration
+        run: bun x vitest run --project dom packages/core/src/infrastructure/db/env.spec.ts
+      - run: bun x vitest run --project db-node --project integration packages/db/test/sqlite-migration.spec.ts packages/db/test/postgresql-migration.spec.ts packages/db/proxy-reader.integration.spec.ts --maxWorkers 1
+
+  database-gate:
+    name: Database gate
+    needs: [changes, journals, migrations]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require selected database checks
+        env:
+          CHANGES: ${{ needs.changes.result }}
+          JOURNALS: ${{ needs.journals.result }}
+          MIGRATIONS: ${{ needs.migrations.result }}
+          RUN_MIGRATIONS: ${{ needs.changes.outputs.migrations }}
+        run: |
+          test "$CHANGES" = success
+          test "$RUN_MIGRATIONS" = true || test "$RUN_MIGRATIONS" = false
+          if [ "$RUN_MIGRATIONS" = true ]; then
+            test "$JOURNALS" = success
+            test "$MIGRATIONS" = success
+          fi
@@ -0,0 +1,115 @@
+name: "[Deployment] Beta Release"
+
+on:
+  workflow_dispatch:
+    inputs:
+      send-notifications:
+        type: boolean
+        required: false
+        default: true
+        description: Send notifications
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  create-and-merge-pr:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Discord notification
+        if: ${{ inputs.send-notifications }}
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "Beta release has been triggered: [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Get Next Version
+        id: semver
+        uses: ietf-tools/semver-action@v1
+        with:
+          token: ${{ github.token }}
+          branch: next
+      - name: Create pull request
+        id: create-pull-request
+        run: |
+          pr_url="$(gh pr list --base beta --head next --state open --json url --jq '.[0].url // empty')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --title "chore(release): release ${{ steps.semver.outputs.next }}-beta" \
+              --body "Detected change to be ${{ steps.semver.outputs.bump }}<br/>Bump version from ${{ steps.semver.outputs.current }} to ${{ steps.semver.outputs.next }}-beta" \
+              --base beta \
+              --head next \
+              --label automerge)"
+          fi
+          echo "url=$pr_url" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${pr_url##*/}" >> "$GITHUB_OUTPUT"
+        env:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+      - name: Discord notification
+        if: ${{ inputs.send-notifications }}
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "Created a release PR ${{ steps.create-pull-request.outputs.url }} for version ${{ steps.semver.outputs.next }}-beta (new behaviour: ${{ steps.semver.outputs.bump }})"
+      - name: Obtain token
+        id: obtainApprovalToken
+        uses: actions/create-github-app-token@v3
+        with:
+          private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
+          permission-pull-requests: write
+      - name: Approve PR
+        env:
+          GITHUB_TOKEN: ${{ steps.obtainApprovalToken.outputs.token }}
+        run: |
+          gh pr review "${{ steps.create-pull-request.outputs.url }}" --approve --body "Automatically approved by GitHub Action"
+      - name: Obtain token
+        id: obtainMergeToken
+        uses: actions/create-github-app-token@v3
+        with:
+          private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
+          permission-contents: write # write to beta branch (due to merge)
+          permission-pull-requests: write # merge pull request
+      - id: automerge
+        if: ${{ steps.semver.outputs.bump != 'major' }}
+        name: automerge
+        uses: "pascalgn/automerge-action@v0.16.4"
+        env:
+          GITHUB_TOKEN: ${{ steps.obtainMergeToken.outputs.token }}
+          MERGE_METHOD: merge # we prefer merge commits for merging to beta
+          MERGE_COMMIT_MESSAGE: "chore(release): release ${{ steps.semver.outputs.next }}-beta"
+          MERGE_DELETE_BRANCH: false # never set to true!
+          PULL_REQUEST: "${{ steps.create-pull-request.outputs.pr_number }}"
+          MERGE_RETRIES: 20 # 20 retries * MERGE_RETRY_SLEEP until step fails
+          MERGE_RETRY_SLEEP: 10000 # 10 seconds * MERGE_RETRIES until step fails
+          MERGE_REQUIRED_APPROVALS: 0 # do not require approvals
+
+      - name: Merged Discord notification
+        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && inputs.send-notifications }}
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "Merged PR ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}-beta"
+      - name: Major Bump Discord notification
+        if: ${{ steps.semver.outputs.bump == 'major' && inputs.send-notifications }}
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "The release PR must be manually merged because the next version is a major version: ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}-beta"
+      - name: Discord Fail Notification
+        if: ${{ failure() && inputs.send-notifications }}
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "The beta release workflow [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) has failed"
@@ -5,6 +5,7 @@ on:
    branches:
      - main
      - beta
+      - next
      - dev
  workflow_dispatch:
    inputs:
@@ -12,7 +13,7 @@ on:
        type: boolean
        required: false
        default: true
-        description: Send notifications
+        description: Send notifications when redeploying an existing release

 permissions:
  contents: write # Required to update package.json version
@@ -32,14 +33,16 @@ jobs:
  release:
    name: Create tag and release
    runs-on: ubuntu-latest
+    timeout-minutes: 5
    env:
-      SKIP_RELEASE: ${{ github.event_name == 'workflow_dispatch' || github.ref_name == 'dev' }}
+      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 || github.ref }}
-
+      git_ref: ${{ steps.read-git-ref.outputs.ref || steps.read-semver.outputs.version || github.ref }}
+      skipped: ${{ env.SKIP_RELEASE }}
+      upstream_sync: ${{ steps.update-upstream.outcome }}
    steps:
-      - run: echo "Skipping release for workflow_dispatch event"
+      - run: echo "Manual dispatch redeploys the latest existing release without creating a new one"
        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"
@@ -49,29 +52,44 @@ jobs:
      - name: Obtain token
        if: env.SKIP_RELEASE == 'false'
        id: obtainToken
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          app-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
-          permission-contents: write # required to commit package.json & changelog changes, merge them to dev and publish the release
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
+          permission-contents: write # required to commit package.json & changelog changes, merge them to dev / next and publish the release

-      - uses: actions/checkout@v5
-        if: env.SKIP_RELEASE == 'false'
+      - uses: actions/checkout@v7
+        if: env.SKIP_RELEASE == 'false' || github.ref_name == 'main' || github.ref_name == 'beta'
        with:
+          fetch-depth: 0
          persist-credentials: false
-      - uses: pnpm/action-setup@v4
-        if: env.SKIP_RELEASE == 'false'
-      - uses: actions/setup-node@v5
+      - uses: oven-sh/setup-bun@v2
        if: env.SKIP_RELEASE == 'false'
        with:
-          node-version: 22.21.0
-          cache: "pnpm"
-      - run: npm i -g pnpm
-        if: env.SKIP_RELEASE == 'false'
-      - name: Install dependencies
+          bun-version: 1.4.2
+      - name: Verify major release intent
        if: env.SKIP_RELEASE == 'false'
        run: |
-          pnpm install
+          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: bun install --frozen-lockfile
      - name: Run Semantic Release
        if: env.SKIP_RELEASE == 'false'
        env:
@@ -81,7 +99,7 @@ jobs:
          GIT_COMMITTER_NAME: "Releases Homarr"
          GIT_COMMITTER_EMAIL: "175486441+homarr-releases[bot]@users.noreply.github.com"
        run: |
-          pnpm release
+          bun run release
      - name: Read semver output
        # We read the last tag either from the created release or from the current branch, this is to rerun the deployment job for the currently released version when it failed
        if: env.SKIP_RELEASE == 'false' || github.ref_name == 'main' || github.ref_name == 'beta'
@@ -94,109 +112,177 @@ jobs:
        id: read-git-ref
        run: |
          echo "ref=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
-      - name: Update dev branch
+      - name: Update dev / next branch
+        id: update-upstream
        if: env.SKIP_RELEASE == 'false'
-        continue-on-error: true # Prevent pipeline from failing when merge fails
+        # Finish publishing the already-created release, then fail in the publish job if synchronization did not work.
+        continue-on-error: true
        env:
          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
+          UPSTREAM_BRANCH: ${{ github.ref_name == 'main' && 'dev' || 'next' }}
+          RELEASE_REF: ${{ steps.read-git-ref.outputs.ref }}
        run: |
          git config user.name "Releases Homarr"
          git config user.email "175486441+homarr-releases[bot]@users.noreply.github.com"
-          git remote set-url origin https://x-access-token:${{ steps.obtainToken.outputs.token }}@github.com/${{ github.repository }}.git
-          git fetch origin dev
-          git checkout dev
-          git pull origin dev
-          git rebase ${{ github.ref_name }}
-          git push origin dev
+          git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git fetch origin "$UPSTREAM_BRANCH"
+
+          # Dependency installation can modify generated files in the release checkout.
+          sync_dir="$(mktemp -d "${RUNNER_TEMP}/homarr-release-sync.XXXXXX")"
+          trap 'git worktree remove --force "$sync_dir"' EXIT
+          git worktree add --detach "$sync_dir" FETCH_HEAD
+          git -C "$sync_dir" merge --no-edit "$RELEASE_REF"
+          git -C "$sync_dir" push origin "HEAD:${UPSTREAM_BRANCH}"
  build-amd64:
    name: Build docker image for amd64
    needs: release
    runs-on: ubuntu-latest
+    timeout-minutes: 15
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
        with:
          ref: ${{ needs.release.outputs.git_ref }}

      - name: Docker meta
        id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
        with:
          images: "${{ env.GHCR_REPO }}"

      - name: Log in to the Container registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      - name: Build and push by digest
        id: build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
        with:
          context: .
          network: host
          platforms: linux/amd64
          labels: ${{ steps.meta.outputs.labels }}
          outputs: type=image,"name=${{ env.GHCR_REPO }}",push-by-digest=true,name-canonical=true,push=true
+          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 }}
        env:
          SKIP_ENV_VALIDATION: true
-
  build-arm64:
    name: Build docker image for arm64
    needs: release
    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 20
    outputs:
      digest: ${{ steps.build.outputs.digest }}
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
        with:
          ref: ${{ needs.release.outputs.git_ref }}

      - name: Docker meta
        id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
        with:
          images: "${{ env.GHCR_REPO }}"

      - name: Log in to the Container registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      - name: Build and push by digest
        id: build
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
        with:
          context: .
          network: host
          platforms: linux/arm64
          labels: ${{ steps.meta.outputs.labels }}
          outputs: type=image,"name=${{ env.GHCR_REPO }}",push-by-digest=true,name-canonical=true,push=true
+          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 }}
        env:
          SKIP_ENV_VALIDATION: true
+  extract-asset-amd64:
+    name: Extract amd64 asset from docker image
+    needs: [release, build-amd64]
+    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
+        with:
+          digest: "${{ env.GHCR_REPO }}@${{ needs.build-amd64.outputs.digest }}"
+          architecture: amd64
+          release-tag: ${{ needs.release.outputs.version }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}

+  extract-asset-arm64:
+    name: Extract arm64 asset from docker image
+    needs: [release, build-arm64]
+    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
+        with:
+          digest: "${{ env.GHCR_REPO }}@${{ needs.build-arm64.outputs.digest }}"
+          architecture: arm64
+          release-tag: ${{ needs.release.outputs.version }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
  publish:
    name: Complete deployment and notify
-    needs: [release, build-amd64, build-arm64]
+    needs: [release, build-amd64, build-arm64, extract-asset-amd64, extract-asset-arm64]
    runs-on: ubuntu-latest
+    timeout-minutes: 5
    env:
      NEXT_VERSION: ${{ needs.release.outputs.version }}
      DEPLOY_LATEST: ${{ github.ref_name == 'main' }}
      DEPLOY_BETA: ${{ github.ref_name == 'beta' }}
    steps:
+      - name: Obtain token
+        if: needs.release.outputs.skipped == 'false'
+        id: obtainToken
+        uses: actions/create-github-app-token@v3
+        with:
+          private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
+          permission-contents: write # required to publish the release
+
      - name: Log in to the Container registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -222,9 +308,37 @@ jobs:
            ${{ env.GHCR_REPO }}@${{ needs.build-amd64.outputs.digest }} \
            ${{ env.GHCR_REPO }}@${{ needs.build-arm64.outputs.digest }}

+      - name: Publish release
+        if: needs.release.outputs.skipped == 'false'
+        env:
+          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
+        run: |
+          gh release edit --repo ${{ github.repository }} ${{ needs.release.outputs.version }} --draft=false
+
+      - name: Verify dev / next synchronization
+        if: needs.release.outputs.skipped == 'false' && needs.release.outputs.upstream_sync != 'success'
+        run: |
+          echo "::error::The released commit was not synchronized back to the upstream development branch."
+          exit 1
+
      - name: Discord notification
+        if: github.event_name != 'workflow_dispatch' || inputs['send-notifications']
        env:
          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        uses: Ilshidur/action-discord@master
+        uses: Ilshidur/action-discord@0.4.0
        with:
          args: "Successfully deployed images for branch **${{ github.ref_name }}**. Tagged as **${{env.NEXT_VERSION}}**."
+
+  notify-failure:
+    name: Notify deployment failure
+    if: ${{ always() && (failure() || cancelled()) && (github.event_name != 'workflow_dispatch' || inputs['send-notifications']) }}
+    needs: [release, build-amd64, build-arm64, extract-asset-amd64, extract-asset-arm64, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Discord failure notification
+        env:
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+        uses: Ilshidur/action-discord@0.4.0
+        with:
+          args: "The deployment for branch **${{ github.ref_name }}** failed or was cancelled: [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"
@@ -0,0 +1,70 @@
+name: "[Deployment] Documentation"
+
+on:
+  push:
+    branches: ["dev"]
+    paths:
+      - "apps/docs/**"
+      - "packages/**"
+      - "tooling/**"
+      - "tools/motion-reel/three/**"
+      - "package.json"
+      - "bun.lock"
+      - "bunfig.toml"
+      - "turbo.json"
+      - ".github/workflows/deployment-docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  SKIP_ENV_VALIDATION: true
+  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 }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - name: Setup
+        uses: ./tooling/github/setup
+        with:
+          next-cache: "docs"
+          turbo-cache: "true"
+      - name: Build docs
+        run: bun run turbo run build --filter=@homarr/docs
+        env:
+          CI: "true"
+      - name: Validate exported links and search
+        run: |
+          bun run --filter @homarr/docs validate:links
+          bun run --filter @homarr/docs verify:search
+          bun run --filter @homarr/docs verify:seo
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: "apps/docs/out"
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
@@ -3,6 +3,7 @@ name: "[Deployment] Automatic Weekly Release"
 on:
  schedule:
    - cron: "0 19 * * 5" # https://crontab.guru/#0_19_*_*_5
+      timezone: Europe/Zurich
  workflow_dispatch:
    inputs:
      send-notifications:
@@ -18,16 +19,17 @@ permissions:
 jobs:
  create-and-merge-pr:
    runs-on: ubuntu-latest
+    timeout-minutes: 10
    steps:
      - name: Discord notification
-        if: ${{ github.events.inputs.send-notifications }}
+        if: ${{ github.event_name == 'schedule' || inputs.send-notifications }}
        env:
          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        uses: Ilshidur/action-discord@master
+        uses: Ilshidur/action-discord@0.4.0
        with:
          args: "Automatic release has been triggered: [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"
      - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - name: Get Next Version
@@ -36,44 +38,65 @@ jobs:
        with:
          token: ${{ github.token }}
          branch: dev
+          noNewCommitBehavior: silent
+          noVersionBumpBehavior: silent
+      - name: No release needed
+        if: ${{ steps.semver.outputs.bump == '' || steps.semver.outputs.bump == 'none' }}
+        run: echo "No release-worthy commits were found since ${{ steps.semver.outputs.current }}." >> "$GITHUB_STEP_SUMMARY"
      - name: Create pull request
-        run: 'gh pr create --title "chore(release): automatic release ${{ steps.semver.outputs.next }}" --body "**This is an automatic release**.<br/>Manual action may be required for major bumps.<br/>Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}``" --base main --head dev --label automerge'
+        id: create-pull-request
+        if: ${{ steps.semver.outputs.bump != '' && steps.semver.outputs.bump != 'none' }}
+        run: |
+          pr_url="$(gh pr list --base main --head dev --state open --json url --jq '.[0].url // empty')"
+          if [[ -z "$pr_url" ]]; then
+            pr_url="$(gh pr create \
+              --title "chore(release): automatic release ${{ steps.semver.outputs.next }}" \
+              --body "**This is an automatic release**.<br/>Manual action may be required for major bumps.<br/>Detected change to be ``${{ steps.semver.outputs.bump }}``<br/>Bump version from ``${{ steps.semver.outputs.current }}`` to ``${{ steps.semver.outputs.next }}``" \
+              --base main \
+              --head dev \
+              --label automerge)"
+          fi
+          echo "url=$pr_url" >> "$GITHUB_OUTPUT"
+          echo "pr_number=${pr_url##*/}" >> "$GITHUB_OUTPUT"
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
      - name: Discord notification
-        if: ${{ github.events.inputs.send-notifications }}
+        if: ${{ steps.create-pull-request.outcome == 'success' && (github.event_name == 'schedule' || inputs.send-notifications) }}
        env:
          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        uses: Ilshidur/action-discord@master
+        uses: Ilshidur/action-discord@0.4.0
        with:
          args: "Created a release PR ${{ steps.create-pull-request.outputs.url }} for version ${{ steps.semver.outputs.next }} (new behaviour: ${{ steps.semver.outputs.bump }})"
      - name: Obtain token
        id: obtainApprovalToken
-        uses: actions/create-github-app-token@v2
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.RENOVATE_APPROVE_PRIVATE_KEY }}
-          app-id: ${{ secrets.RENOVATE_APPROVE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_APPROVE_CLIENT_ID }}
          permission-pull-requests: write
      - name: Approve PR
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
        env:
          GITHUB_TOKEN: ${{ steps.obtainApprovalToken.outputs.token }}
        run: |
-          gh pr review --approve --body "Automatically approved by GitHub Action"
+          gh pr review "${{ steps.create-pull-request.outputs.url }}" --approve --body "Automatically approved by GitHub Action"
      - name: Obtain token
        id: obtainMergeToken
-        uses: actions/create-github-app-token@v2
+        if: ${{ steps.create-pull-request.outcome == 'success' }}
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          app-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
          permission-contents: write # write to main branch (due to merge)
          permission-pull-requests: write # merge pull request
      - id: automerge
-        if: ${{ steps.semver.outputs.bump != 'major' }}
+        if: ${{ steps.create-pull-request.outcome == 'success' && steps.semver.outputs.bump != 'major' }}
        name: automerge
        uses: "pascalgn/automerge-action@v0.16.4"
        env:
          GITHUB_TOKEN: ${{ steps.obtainMergeToken.outputs.token }}
-          MERGE_METHOD: merge # we prefer merge commits for merging to master
+          MERGE_METHOD: merge # we prefer merge commits for merging to main
          MERGE_COMMIT_MESSAGE: "chore(release): automatic release ${{ steps.semver.outputs.next }}"
          MERGE_DELETE_BRANCH: false # never set to true!
          PULL_REQUEST: "${{ steps.create-pull-request.outputs.pr_number }}"
@@ -82,23 +105,23 @@ jobs:
          MERGE_REQUIRED_APPROVALS: 0 # do not require approvals

      - name: Merged Discord notification
-        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && github.events.inputs.send-notifications }}
+        if: ${{ steps.automerge.outputs.mergeResult == 'merged' && (github.event_name == 'schedule' || inputs.send-notifications) }}
        env:
          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        uses: Ilshidur/action-discord@master
+        uses: Ilshidur/action-discord@0.4.0
        with:
          args: "Merged PR ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}"
      - name: Major Bump Discord notification
-        if: ${{ steps.semver.outputs.bump == 'major' && github.events.inputs.send-notifications }}
+        if: ${{ steps.semver.outputs.bump == 'major' && (github.event_name == 'schedule' || inputs.send-notifications) }}
        env:
          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        uses: Ilshidur/action-discord@master
+        uses: Ilshidur/action-discord@0.4.0
        with:
          args: "The release PR must be manually merged because the next version is a major version: ${{ steps.create-pull-request.outputs.url }} for release ${{ steps.semver.outputs.next }}"
      - name: Discord Fail Notification
-        if: failure() && github.events.inputs.send-notifications
+        if: ${{ failure() && (github.event_name == 'schedule' || inputs.send-notifications) }}
        env:
          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-        uses: Ilshidur/action-discord@master
+        uses: Ilshidur/action-discord@0.4.0
        with:
          args: "The automatic release workflow [run ${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) has failed"
@@ -0,0 +1,39 @@
+name: "[Docs] Update Contributors"
+
+on:
+  schedule:
+    - cron: "0 12 * * FRI"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+env:
+  GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+  HOMARR_CROWDIN_TOKEN: "${{ secrets.HOMARR_CROWDIN_TOKEN }}"
+  HOMARR_LABS_CROWDIN_TOKEN: "${{ secrets.HOMARR_LABS_CROWDIN_TOKEN }}"
+  SKIP_ENV_VALIDATION: true
+
+jobs:
+  dump:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: dev
+
+      - name: Setup
+        uses: ./tooling/github/setup
+
+      - name: Dump contributors
+        working-directory: apps/docs
+        run: bun run api-dump-contributors
+
+      - name: Commit updated contributors
+        uses: EndBug/add-and-commit@v10
+        with:
+          add: "apps/docs/public"
+          default_author: github_actor
+          message: "chore(docs): update contributors"
+          push: true
@@ -0,0 +1,38 @@
+name: "[Docs] Update OpenAPI Spec"
+
+on:
+  schedule:
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+env:
+  SKIP_ENV_VALIDATION: true
+
+jobs:
+  update-spec:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: dev
+
+      - name: Setup
+        uses: ./tooling/github/setup
+
+      - name: Copy env
+        run: cp .env.example .env
+
+      - name: Generate and validate OpenAPI spec
+        run: bun run scripts:update-openapi
+
+      - name: Commit updated spec
+        uses: EndBug/add-and-commit@v10
+        with:
+          add: "apps/docs/public/api/"
+          default_author: github_actor
+          message: "chore(docs): update OpenAPI spec"
+          push: true
@@ -0,0 +1,45 @@
+name: "[Deployments] Validate prebuilt debian dependencies"
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    branches: ["**"]
+    paths: [".github/actions/prebuilt-debian/**", "deployments/prebuilt-debian/**"]
+
+jobs:
+  prebuilt-debian-validate-amd64:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - name: Validate prebuilt dependencies for amd64
+        id: validate-amd64
+        uses: ./.github/actions/prebuilt-debian
+        with:
+          architecture: amd64
+
+      - name: Check extracted files for amd64
+        run: |
+          if [ ! -f "${{ steps.validate-amd64.outputs.path }}/better_sqlite3.node" ]; then
+            echo "better_sqlite3.node not found for amd64!"
+            exit 1
+          fi
+  prebuilt-debian-validate-arm64:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+      - name: Validate prebuilt dependencies for arm64
+        id: validate-arm64
+        uses: ./.github/actions/prebuilt-debian
+        with:
+          architecture: arm64
+
+      - name: Check extracted files for arm64
+        run: |
+          if [ ! -f "${{ steps.validate-arm64.outputs.path }}/better_sqlite3.node" ]; then
+            echo "better_sqlite3.node not found for arm64!"
+            exit 1
+          fi
@@ -5,14 +5,22 @@ permissions:

 on:
  pull_request:
-    branches: ["*"]
+    branches: ["**"]
    paths: [".github/renovate.json5"]

 jobs:
  renovate-validate:
    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    env:
+      # The optional RE2 addon uses V8 APIs; validation can use JavaScript regexes.
+      RENOVATE_X_IGNORE_RE2: "true"
    steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.4.2
      - run: |
-          npx --yes --package renovate -- \
+          bun x --package renovate \
              renovate-config-validator --strict .github/renovate.json5
@@ -2,73 +2,40 @@ permissions: {}

 on:
  release:
-    types: [published]
+    types: [released]

 jobs:
-  trigger-docs-release:
-    name: Trigger Documentation Release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Obtain token
-        id: obtainToken
-        uses: actions/create-github-app-token@v2
-        with:
-          private-key: ${{ secrets.HOMARR_DOCS_RELEASE_APP_PRIVATE_KEY }}
-          app-id: ${{ vars.HOMARR_DOCS_RELEASE_APP_ID }}
-          owner: homarr-labs
-          repositories: |
-            documentation
-          permission-contents: write # required to dispatch repository workflow
-      - name: Trigger documentation release
-        env:
-          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
-          SOURCE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          curl -X POST \
-            -H "Authorization: token $GITHUB_TOKEN" \
-            -H "Accept: application/vnd.github+json" \
-            https://api.github.com/repos/homarr-labs/documentation/dispatches \
-            -d @- <<EOF
-          {
-            "event_type": "trigger-release",
-            "client_payload": {
-              "tag": "${SOURCE_TAG}"
-            }
-          }
-          EOF
  update-bug-report-template:
    name: Update Bug Report Template
    runs-on: ubuntu-latest
+    timeout-minutes: 5
    steps:
      - name: Obtain token
        id: obtainToken
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.RENOVATE_MERGE_PRIVATE_KEY }}
-          app-id: ${{ secrets.RENOVATE_MERGE_APP_ID }}
+          client-id: ${{ vars.RENOVATE_MERGE_CLIENT_ID }}
          permission-contents: write # required to commit to branch
          permission-pull-requests: write # required to create pr & enable automerge
      - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
        with:
          token: ${{ steps.obtainToken.outputs.token }}
+          ref: dev
      - name: Setup
        uses: ./tooling/github/setup
-      - run: pnpm run scripts:update-bug-report-template
+      - run: bun run scripts:update-bug-report-template
        env:
          NEXT_VERSION: ${{ github.event.release.tag_name }}
-      - name: Commit changes
-        run: |
-          git config --global user.email "175486441+homarr-releases[bot]@users.noreply.github.com"
-          git config --global user.name "Releases Homarr"
-          git checkout -b update-bug-report-template
-          git add .
-          git commit -m "chore: update bug report template"

      - name: Create Pull Request
        id: create-pull-request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
        with:
+          add-paths: .github/ISSUE_TEMPLATE/bug_report.yml
+          commit-message: "chore: update bug report template"
+          author: Releases Homarr <175486441+homarr-releases[bot]@users.noreply.github.com>
          token: ${{ steps.obtainToken.outputs.token }}
          branch: update-bug-report-template
          base: dev
@@ -1,5 +1,6 @@
 permissions:
  statuses: write
+  contents: read

 on:
  pull_request:
@@ -7,20 +8,29 @@ on:

 jobs:
  skip-stability-days:
-    if: ${{ !startsWith(github.head_ref, 'renovate/') }}
+    if: ${{ !startsWith(github.head_ref, 'renovate/') && github.event.pull_request.head.repo.full_name == github.repository }}
    name: Skip Stability Days
    runs-on: ubuntu-latest
+    timeout-minutes: 1
    steps:
      - name: Add status check
        env:
          GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
        run: |
-          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'
+          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
@@ -9,36 +9,32 @@ env:
  GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
  CROWDIN_TOKEN: "${{ secrets.CROWDIN_UPDATE_CONTRIBUTORS_TOKEN }}"

+permissions:
+  contents: read
 jobs:
  update-contributors:
    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [22]
+    timeout-minutes: 2
    steps:
      - name: Obtain token
        id: obtainToken
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.HOMARR_UPDATE_CONTRIBUTORS_PRIVATE_KEY }}
-          app-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_APP_ID }}
+          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_CLIENT_ID }}
          permission-contents: write # required to commit to branch
          permission-pull-requests: write # required to create pr & enable automerge

      - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
        env:
          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
-
-      - uses: pnpm/action-setup@v4
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v5
+      - uses: oven-sh/setup-bun@v2
        with:
-          node-version: ${{ matrix.node-version }}
-          cache: "pnpm"
+          bun-version: 1.4.2

      - name: Run update script
-        run: node ./scripts/update-contributors.mjs
+        run: bun ./scripts/update-contributors.mjs

      - name: Commit changes
        env:
@@ -51,7 +47,7 @@ jobs:

      - name: Create Pull Request
        id: create-pull-request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ steps.obtainToken.outputs.token }}
          branch: update-contributors
@@ -17,22 +17,23 @@ jobs:
      group: update-integration
      cancel-in-progress: false
    runs-on: ubuntu-latest
+    timeout-minutes: 5
    steps:
      - name: Obtain token
        id: obtainToken
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
        with:
          private-key: ${{ secrets.HOMARR_UPDATE_CONTRIBUTORS_PRIVATE_KEY }}
-          app-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_APP_ID }}
+          client-id: ${{ vars.HOMARR_UPDATE_CONTRIBUTORS_CLIENT_ID }}
          permission-contents: write # required to commit to branch
          permission-pull-requests: write # required to create pr & enable automerge
      - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
        env:
          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
      - name: Setup
        uses: ./tooling/github/setup
-      - run: pnpm run scripts:update-readme-integrations
+      - run: bun run scripts:update-readme-integrations
      - name: Commit changes
        env:
          GITHUB_TOKEN: ${{ steps.obtainToken.outputs.token }}
@@ -44,7 +45,7 @@ jobs:

      - name: Create Pull Request
        id: create-pull-request
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ steps.obtainToken.outputs.token }}
          branch: update-integrations-readme
@@ -0,0 +1,65 @@
+name: Validate documentation
+
+on:
+  pull_request:
+    paths:
+      - "apps/docs/**"
+      - "apps/nextjs/src/app/api/**"
+      - "packages/definitions/src/**"
+      - "packages/widgets/src/**"
+      - "packages/custom-widgets/src/**"
+      - "packages/ui/src/**"
+      - "packages/workshop/src/**"
+      - "packages/api/src/**"
+      - "packages/auth/src/**"
+      - "packages/integrations/src/**"
+      - "tools/motion-reel/three/**"
+      - "tooling/**"
+      - "bun.lock"
+      - "package.json"
+      - "bunfig.toml"
+      - "turbo.json"
+      - ".github/workflows/deployment-docs.yml"
+      - ".github/workflows/validate-docs.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: validate-docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs:
+    name: Build and validate docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      SKIP_ENV_VALIDATION: true
+      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 }}
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+      - name: Setup
+        uses: ./tooling/github/setup
+        with:
+          next-cache: "docs"
+          turbo-cache: "true"
+      - name: Validate the published API schema against the application
+        run: bun run check:openapi
+      - name: Validate browser access and API schema rendering
+        run: bun x vitest run 'apps/nextjs/src/app/api/[...trpc]/route.spec.ts' apps/docs/src/lib/openapi.spec.ts
+      - name: Build docs
+        run: bun run turbo run build --filter=@homarr/docs
+        env:
+          CI: "true"
+      - name: Validate exported links, search, and metadata
+        run: |
+          bun run --filter @homarr/docs validate:links
+          bun run --filter @homarr/docs verify:search
+          bun run --filter @homarr/docs verify:seo
@@ -0,0 +1,247 @@
+name: Workshop
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/workshop.yml"
+      - "tooling/github/**"
+      - "apps/workshop/**"
+      - "apps/docs/**"
+      - "packages/common/**"
+      - "packages/core/**"
+      - "packages/custom-widgets/**"
+      - "packages/definitions/**"
+      - "packages/db/**"
+      - "packages/server-settings/**"
+      - "packages/settings/**"
+      - "packages/translation/**"
+      - "packages/ui/**"
+      - "packages/validation/**"
+      - "packages/workshop/**"
+      - "tooling/typescript/**"
+      - "patches/**"
+      - "package.json"
+      - "bun.lock"
+      - "bunfig.toml"
+      - "turbo.json"
+  push:
+    branches: [dev, v2, release/v2, main]
+    paths:
+      - ".github/workflows/workshop.yml"
+      - "tooling/github/**"
+      - "apps/workshop/**"
+      - "apps/docs/**"
+      - "packages/common/**"
+      - "packages/core/**"
+      - "packages/custom-widgets/**"
+      - "packages/definitions/**"
+      - "packages/db/**"
+      - "packages/server-settings/**"
+      - "packages/settings/**"
+      - "packages/translation/**"
+      - "packages/ui/**"
+      - "packages/validation/**"
+      - "packages/workshop/**"
+      - "tooling/typescript/**"
+      - "patches/**"
+      - "package.json"
+      - "bun.lock"
+      - "bunfig.toml"
+      - "turbo.json"
+
+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:
+  production-smoke:
+    if: github.event_name == 'pull_request'
+    name: Production image smoke (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24.18.0
+      - name: Set up Docker Buildx
+        if: "!env.ACT"
+        uses: docker/setup-buildx-action@v4
+      - name: Build the production image
+        if: "!env.ACT"
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: apps/workshop/Dockerfile
+          target: production
+          platforms: linux/${{ matrix.arch }}
+          load: true
+          tags: homarr-workshop:smoke
+          cache-from: type=gha,scope=workshop-linux-${{ matrix.arch }}
+          cache-to: type=gha,scope=workshop-linux-${{ matrix.arch }},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 }}
+      - name: Exercise the production image
+        if: "!env.ACT"
+        env:
+          WORKSHOP_IMAGE_TEST_IMAGE: homarr-workshop:smoke
+        run: sh apps/workshop/test-image.sh
+      - name: Build and exercise the production image with Act
+        if: env.ACT
+        env:
+          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 }}
+        run: sh apps/workshop/test-image.sh
+
+  validate:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+        if: "!env.ACT"
+      - run: docker compose --env-file apps/workshop/.env.staging.example -f apps/workshop/docker-compose.staging.yml config --quiet
+
+  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
+        if: "!env.ACT"
+      - 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
+          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-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
+        if: "!env.ACT"
+      - 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
+          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:
+    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"
@@ -2,6 +2,7 @@

 # dependencies
 node_modules
+.bun-cache/
 .pnp
 .pnp.js
 .idea/
@@ -15,6 +16,7 @@ out/
 next-env.d.ts

 # artifacts
+.ai-evaluations/
 packages/db/migrations/*/migrate.cjs

 # nitro
@@ -23,6 +25,8 @@ packages/db/migrations/*/migrate.cjs

 # production
 build
+tools/homarr-dev/homarr
+tools/homarr-dev/homarr-dev

 # misc
 .DS_Store
@@ -32,7 +36,7 @@ build
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-.pnpm-debug.log*
+bun-debug.log*

 # local env files
 .env
@@ -66,5 +70,27 @@ e2e/shared/tmp
 #personal backgrounds
 apps/nextjs/public/images/background.png

-# next-intl
-en.d.json.ts
+
+
+# personal agent config
+.opencode
+.agents/*
+!.agents/skills/
+skills-lock.json
+
+# docusaurus
+apps/docs/.docusaurus
+apps/docs/build
+.bun-cache
+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/
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mantine": {
+      "command": "bun",
+      "args": ["x", "@mantine/mcp-server@9.6.0"]
+    }
+  }
+}
@@ -1,5 +0,0 @@
-# Expo doesn't play nice with pnpm by default. 
-# The symbolic links of pnpm break the rules of Expo monorepos.
-# @link https://docs.expo.dev/guides/monorepos/#common-issues
-node-linker=hoisted
-strict-peer-dependencies=false
@@ -1 +1 @@
-22.21.0
+24.18.0
@@ -0,0 +1,22 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 120,
+  "endOfLine": "lf",
+  "sortPackageJson": true,
+  "ignorePatterns": [
+    "**/*.cjs",
+    "**/lang/**",
+    "static-data/**",
+    "CHANGELOG.md",
+    "apps/docs/.next/**",
+    "apps/docs/out/**",
+    "apps/docs/blog/2022/**",
+    "apps/docs/blog/2023/**",
+    "apps/docs/blog/2024/**",
+    "apps/docs/blog/2025/**",
+    "apps/docs/blog/authors.yml",
+    "apps/docs/public/api/open-api-schema.json",
+    "packages/custom-widgets/src/core/component-catalog.generated.json",
+    "apps/docs/public/custom-widgets/component-catalog-v1.json"
+  ]
+}
@@ -0,0 +1,65 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "typescript", "unicorn", "oxc", "react", "import", "jsx-a11y"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "pedantic": "off",
+    "perf": "off",
+    "style": "off",
+    "restriction": "off",
+    "nursery": "off"
+  },
+  "rules": {
+    "eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
+    "typescript/consistent-type-imports": ["warn", { "prefer": "type-imports", "fixStyle": "separate-type-imports" }],
+    "typescript/no-non-null-assertion": "error",
+    "import/consistent-type-specifier-style": ["error", "prefer-top-level"],
+    "unicorn/no-new-array": "warn",
+    "unicorn/no-useless-spread": "warn",
+    "unicorn/no-useless-length-check": "warn",
+    "unicorn/no-useless-fallback-in-spread": "warn",
+    "jsx-a11y/prefer-tag-over-role": "warn",
+    "oxc/const-comparisons": "warn",
+    "react-hooks/exhaustive-deps": "warn",
+    "react/no-children-prop": "warn",
+    "jsx-a11y/no-autofocus": "warn",
+    "jsx-a11y/img-redundant-alt": "warn",
+    "react/react-in-jsx-scope": "off"
+  },
+  "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/**"
+  ],
+  "settings": {
+    "react": { "version": "19" }
+  }
+}
@@ -26,16 +26,11 @@
        "changelogFile": "CHANGELOG.md"
      }
    ],
-    [
-      "@semantic-release/npm",
-      {
-        "npmPublish": false
-      }
-    ],
+    "./scripts/release-version.mjs",
    [
      "@semantic-release/git",
      {
-        "assets": ["package.json", "CHANGELOG.md"],
+        "assets": ["package.json", "bun.lock", "CHANGELOG.md"],
        "message": "chore(release): ${nextRelease.version} [skip ci]"
      }
    ],
@@ -44,6 +39,7 @@
      {
        "successComment": false,
        "failComment": false,
+        "draftRelease": true,
        "releaseBodyTemplate": "<%= _.truncate(nextRelease.notes, { 'length': 124000, 'omission': '' }) %>"
      }
    ]
@@ -1,13 +0,0 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="db:migration:mysql:generate" type="js.build_tools.npm">
-    <package-json value="$PROJECT_DIR$/package.json" />
-    <command value="run" />
-    <scripts>
-      <script value="db:migration:mysql:generate" />
-    </scripts>
-    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
-    <envs />
-    <method v="2" />
-  </configuration>
-</component>
@@ -6,7 +6,7 @@
      <script value="db:migration:postgresql:generate" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="db:migration:sqlite:generate" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="db:push" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="db:studio" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="dev" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="docker:dev" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="format" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="format:fix" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="test" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="test:ui" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -6,7 +6,7 @@
      <script value="typecheck" />
    </scripts>
    <node-interpreter value="project" />
-    <package-manager value="pnpm" />
+    <package-manager value="bun" />
    <envs />
    <method v="2" />
  </configuration>
@@ -1,7 +1,7 @@
 {
  "recommendations": [
    "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode",
+    "oxc.oxc-vscode",
    "yoavbls.pretty-ts-errors",
    "million.million-lint",
    "lokalise.i18n-ally"
@@ -31,6 +31,5 @@ scopeRangeRegex: "(?:const|let|var)\\s+t\\s*=\\s*(?:await\\s+)?(?:getScopedI18n|
 # refactorTemplates:
 #  - i18n.get("$1")

-
 # If set to true, only enables this custom framework (will disable all built-in frameworks)
-monopoly: true
+monopoly: true
@@ -5,7 +5,7 @@
      "name": "dev",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm dev",
+      "command": "bun run dev",
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    },
@@ -13,37 +13,31 @@
      "name": "docker dev",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm docker:dev",
+      "command": "bun run docker:dev",
      "cwd": "${workspaceFolder}",
-      "skipFiles": [
-        "<node_internals>/**"
-      ]
+      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "lint fix",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm lint:fix",
+      "command": "bun run lint:fix",
      "cwd": "${workspaceFolder}",
-      "skipFiles": [
-        "<node_internals>/**"
-      ]
+      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "format fix",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm format:fix",
+      "command": "bun run format:fix",
      "cwd": "${workspaceFolder}",
-      "skipFiles": [
-        "<node_internals>/**"
-      ]
+      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "db push",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm db:push",
+      "command": "bun run db:push",
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    },
@@ -51,7 +45,7 @@
      "name": "db studio",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm db:studio",
+      "command": "bun run db:studio",
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    },
@@ -59,7 +53,7 @@
      "name": "db migration run",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm db:migration:run",
+      "command": "bun run db:migration:sqlite:run",
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    },
@@ -67,21 +61,17 @@
      "name": "test",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm test",
+      "command": "bun run test",
      "cwd": "${workspaceFolder}",
-      "skipFiles": [
-        "<node_internals>/**"
-      ]
+      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "test ui",
      "type": "node-terminal",
      "request": "launch",
-      "command": "pnpm test:ui",
+      "command": "bun run test:ui",
      "cwd": "${workspaceFolder}",
-      "skipFiles": [
-        "<node_internals>/**"
-      ]
+      "skipFiles": ["<node_internals>/**"]
    }
  ]
 }
@@ -1,13 +1,6 @@
 {
-  "eslint.workingDirectories": [
-    {
-      "mode": "auto"
-    }
-  ],
-  "eslint.experimental.useFlatConfig": true,
-  "typescript.tsdk": "node_modules\\typescript\\lib",
+  "js/ts.tsdk.path": "node_modules\\typescript\\lib",
  "js/ts.implicitProjectConfig.experimentalDecorators": true,
-  "prettier.configPath": "./tooling/prettier/index.mjs",
  "cSpell.words": [
    "ajnart",
    "cqmin",
@@ -34,11 +27,7 @@
  ],
  "i18n-ally.dirStructure": "auto",
  "i18n-ally.displayLanguage": "en",
-  "i18n-ally.enabledFrameworks": [
-    "custom"
-  ],
-  "i18n-ally.localesPaths": [
-    "packages/translation/src/lang",
-  ],
-  "i18n-ally.keystyle": "nested",
+  "i18n-ally.enabledFrameworks": ["custom"],
+  "i18n-ally.localesPaths": ["packages/translation/src/lang"],
+  "i18n-ally.keystyle": "nested"
 }
@@ -0,0 +1,124 @@
+# Homarr Agent Rules
+
+## Repository Structure
+
+```
+homarr/
+├── apps/
+│   ├── nextjs/          # Main Next.js application (port 3000)
+│   ├── docs/            # Next.js + Fumadocs documentation site (@homarr/docs)
+│   ├── tasks/           # Cron-job initialization and scheduling runtime
+│   ├── websocket/       # Standalone tRPC WebSocket server (port 3001)
+│   └── workshop/        # Go/PocketBase Workshop service
+├── packages/
+│   ├── api/             # tRPC appRouter, procedures, OpenAPI
+│   ├── auth/            # NextAuth config, providers, session, API keys
+│   ├── db/              # SQLite and PostgreSQL schemas, migrations, queries
+│   ├── core/            # Env validation, DB/Redis driver factories, logging
+│   ├── definitions/     # Domain enums: WidgetKind, IntegrationKind, permissions
+│   ├── widgets/         # Dashboard widget definitions and 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
+│   ├── cron-jobs-core/  # Cron scheduling primitives
+│   ├── 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
+│   ├── custom-widgets/  # Custom JSX v2 schema, validation, and runtime
+│   ├── onboarding/      # Onboarding studio and setup flow
+│   ├── workshop/        # Homarr-side Workshop client and contracts
+│   └── cli/             # Node CLI for ops (brocli)
+├── tooling/
+│   ├── typescript/      # Base tsconfig
+│   └── github/          # CI setup action
+├── tools/
+│   └── homarr-dev/      # Go CLI for local and PR Docker images
+├── development/         # Dev docker-compose (Redis, MySQL, PostgreSQL)
+├── e2e/                 # E2E test specs
+└── Dockerfile           # Multi-stage production build
+```
+
+## Documentation
+
+Add documentation only when users need the information to set up, use, or troubleshoot Homarr and cannot reasonably discover it from the UI or generated API schema. If a user does not need to know it, do not document it. A code, UI, or API change alone is never a reason to add docs.
+
+Keep warranted documentation concise. Omit UI walkthroughs, visible control descriptions, internal implementation details, and anything already clear from the interface or schema.
+
+Only after this user-need test passes, use these locations:
+
+- New integration → `apps/docs/docs/integrations/<slug>/index.mdx` + `index.ts`
+- New widget → `apps/docs/docs/widgets/<slug>/index.mdx` + `index.ts`
+- Changed API → `apps/docs/docs/management/api/index.mdx`
+- New/changed env vars → `apps/docs/docs/advanced/`
+- New CLI commands → `apps/docs/docs/advanced/command-line/`
+- Auth changes → `apps/docs/docs/advanced/` SSO pages
+- New cron job → `apps/docs/docs/management/tasks.mdx`
+
+## Monorepo Commands
+
+- `bun run dev` — Next.js app only
+- `bun run dev:cli -- dev` — run the developer CLI without installing a global binary
+- `bun run db:seed` — seed default database data explicitly
+- `bun run docker:dev:up` — start the Redis development service in the background
+- `bun run dev:docs` — Fumadocs site only
+- `bun run turbo build` — build all packages
+- `bun run turbo build --filter=@homarr/docs` — build docs only
+- `bun run turbo typecheck` — typecheck all packages
+- `bun run lint` / `bun run format` — oxlint / oxfmt
+
+## Code Style
+
+- Lint: oxlint (not ESLint)
+- Format: oxfmt (not Prettier)
+- UI: Mantine (not Tailwind) — Tailwind is only used in docs app
+- Mantine: use the `mantine` MCP server in `.mcp.json` for current v9 APIs before writing component code. Prefer built-in primitives (`Combobox`/`useCombobox`, the polymorphic `component` prop, `@mantine/hooks`) and check `packages/ui/` for existing conventions first.
+- Icons: @tabler/icons-react
+- Docs app can import from `@homarr/definitions` for shared types
+- Run `bun run dev:cli -- dev` to browse local `homarr:*` images and remote PR images.
+- Run `bun run dev:cli -- build <name>` from a Homarr checkout to build `homarr:<name>` with rebuild provenance.
+- Run `bun run dev:cli -- build --pr <number>` to build a PR locally from a temporary checkout.
+
+## Testing
+
+Add tests only when requested, and only when the test is extremely relevant and will plausibly prevent a future regression in user-visible behavior or a security boundary. Do not add tests that restate implementation details or duplicate stronger coverage. For focused changes, run only the relevant existing or newly requested checks when validation is needed. Do not run broad test, Docker, or E2E suites by default.
+
+## MCP servers
+
+`.mcp.json` declares project-scoped MCP servers. Keep only keyless definitions there; credentials belong in local dotfiles. See [Mantine LLM tooling](https://mantine.dev/guides/llms/) for client-specific setup.
+
+## Agent Skills
+
+Portable skills live in `.agents/skills/`. Read the relevant `SKILL.md` before working in that domain; detailed references are loaded only when needed. Claude-compatible discovery is provided through `.claude/skills`.
+
+- `codebase-context` — architecture, package boundaries, and shared utilities
+- `documentation-sync` — user-critical documentation only
+- `mcp-integration` — safe tRPC-to-MCP exposure
+- `homarr-custom-widget` — safe Custom JSX v2 authoring
+
+<!-- BEGIN:turborepo-agent-rules -->
+
+# This is NOT the Turborepo you know
+
+Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.
+
+Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.
+
+This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. When agent guidance is enabled, keep the block committed to avoid an uncommitted change on the next agent invocation. This repository disables agent guidance in `turbo.json`.
+<!-- END:turborepo-agent-rules -->
@@ -1 +0,0 @@
-* @homarr-labs/maintainers
@@ -1,71 +1,62 @@
-FROM node:22.20.0-alpine AS base
+# syntax=docker/dockerfile:1.25
+
+FROM oven/bun:1.4.2-alpine AS bun-tool
+
+FROM node:24.18.0-alpine AS base

 FROM base AS builder
-RUN apk add --no-cache libc6-compat
-RUN apk update
-
-# Set working directory
+ARG TARGETPLATFORM
 WORKDIR /app
-RUN apk add --no-cache libc6-compat curl bash
-RUN apk update
+COPY --from=bun-tool /usr/local/bin/bun /usr/local/bin/bun
+# Compiler tools stay in the builder for optional native dependency fallbacks.
+RUN apk add --no-cache libstdc++ python3 make g++
+COPY bun.lock bunfig.toml package.json ./
+COPY patches ./patches
+COPY --parents ./apps/*/package.json ./packages/*/package.json ./tooling/*/package.json ./
+RUN --mount=type=cache,id=homarr-bun-cache,target=/root/.bun/install/cache,sharing=locked \
+    npm_config_nodedir=/usr/local bun install --frozen-lockfile --concurrent-scripts=1
+
 COPY . .
-
-RUN corepack enable pnpm && pnpm install --recursive --frozen-lockfile
-
-# Copy static data as it is not part of the build
-COPY static-data ./static-data
 ARG SKIP_ENV_VALIDATION='true'
 ARG CI='true'
 ARG DISABLE_REDIS_LOGS='true'
+ARG TARGETPLATFORM
+RUN --mount=type=secret,id=TURBO_API,env=TURBO_API \
+    --mount=type=secret,id=TURBO_TEAM,env=TURBO_TEAM \
+    --mount=type=secret,id=TURBO_TOKEN,env=TURBO_TOKEN \
+    --mount=type=secret,id=TURBO_REMOTE_CACHE_SIGNATURE_KEY,env=TURBO_REMOTE_CACHE_SIGNATURE_KEY \
+    --mount=type=cache,id=homarr-next-build-${TARGETPLATFORM},target=/app/apps/nextjs/.next/cache,sharing=locked \
+    --mount=type=cache,id=homarr-turbo-${TARGETPLATFORM},target=/app/.turbo,sharing=locked \
+    TURBO_PLATFORM="${TARGETPLATFORM:-linux/amd64}/musl/node-24.18.0" \
+    bun run turbo run build --filter=@homarr/nextjs... --filter=@homarr/cli

-RUN corepack enable pnpm && pnpm build
-
-FROM base AS runner
+FROM alpine:3.24.1 AS runner
 WORKDIR /app
-
-# gettext is required for envsubst, openssl for generating AUTH_SECRET, su-exec for running application as non-root
-RUN apk add --no-cache redis nginx bash gettext su-exec openssl
-RUN mkdir /appdata
+COPY --from=base /usr/local/bin/node /usr/local/bin/node
+# envsubst, privilege drop and AUTH_SECRET generation are used by the entrypoint.
+RUN apk add --no-cache libstdc++ ca-certificates redis nginx bash gettext su-exec openssl && \
+    mkdir -p /appdata /var/cache/nginx /var/log/nginx /var/lib/nginx \
+      /run/nginx /etc/nginx/templates /etc/nginx/ssl/certs && \
+    touch /run/nginx/nginx.pid
 VOLUME /appdata
-
-# Enable homarr cli
 COPY --from=builder /app/packages/cli/cli.cjs /app/apps/cli/cli.cjs
-RUN echo $'#!/bin/bash\ncd /app/apps/cli && node ./cli.cjs "$@"' > /usr/bin/homarr
-RUN chmod +x /usr/bin/homarr
-
-# Don't run production as root
-RUN mkdir -p /var/cache/nginx && \
-    mkdir -p /var/log/nginx && \
-    mkdir -p /var/lib/nginx && \
-    touch /run/nginx/nginx.pid && \
-    mkdir -p /etc/nginx/templates /etc/nginx/ssl/certs
-
-COPY --from=builder /app/apps/nextjs/next.config.ts .
-COPY --from=builder /app/apps/nextjs/package.json .
-
-COPY --from=builder /app/apps/tasks/tasks.cjs ./apps/tasks/tasks.cjs
-COPY --from=builder /app/apps/websocket/wssServer.cjs ./apps/websocket/wssServer.cjs
+# Bundled CLI/migrations resolve the native binding from the application root.
 COPY --from=builder /app/node_modules/better-sqlite3/build/Release/better_sqlite3.node /app/build/better_sqlite3.node
-
+RUN printf '#!/bin/sh\ncd /app/apps/cli && exec node ./cli.cjs "$@"\n' > /usr/bin/homarr && \
+    chmod +x /usr/bin/homarr
 COPY --from=builder /app/packages/db/migrations ./db/migrations
-
-# Automatically leverage output traces to reduce image size
-# https://nextjs.org/docs/advanced-features/output-file-tracing
-COPY --from=builder /app/apps/nextjs/.next/standalone ./
-COPY --from=builder /app/apps/nextjs/.next/static ./apps/nextjs/.next/static
-COPY --from=builder /app/apps/nextjs/public ./apps/nextjs/public
+# Ship only Next's traced production dependencies and application assets.
+COPY --from=builder /app/apps/nextjs/.output/standalone ./
 COPY scripts/run.sh ./run.sh
-COPY --chmod=777 scripts/entrypoint.sh ./entrypoint.sh
+COPY --chmod=755 scripts/entrypoint.sh ./entrypoint.sh
 COPY packages/redis/redis.conf /app/redis.conf
 COPY nginx.conf /etc/nginx/templates/nginx.conf
-
-
 ENV DB_URL='/appdata/db/db.sqlite'
 ENV DB_DIALECT='sqlite'
 ENV DB_DRIVER='better-sqlite3'
 ENV AUTH_PROVIDERS='credentials'
 ENV REDIS_IS_EXTERNAL='false'
 ENV NODE_ENV='production'
-
-ENTRYPOINT [ "/app/entrypoint.sh" ]
+EXPOSE 7575
+ENTRYPOINT ["/app/entrypoint.sh"]
 CMD ["sh", "run.sh"]
@@ -0,0 +1,33 @@
+# Product
+
+## Register
+
+brand
+
+## Users
+
+Self-hosted Homarr users who need to evaluate the project, install it, connect services, find extensions, and reference its APIs. They move between the homepage, documentation, Workshop, API reference, and project updates as one continuous experience.
+
+## Product Purpose
+
+The site explains what Homarr does and gives users reliable paths to install, configure, extend, and operate it. Success means users can identify where they are, move between major surfaces without relearning the navigation, and read technical content comfortably.
+
+## Brand Personality
+
+Practical, technical, welcoming.
+
+## Anti-references
+
+Avoid disconnected microsites, marketing-heavy copy, ornamental dashboards, hidden navigation, and dense long-form pages without visible structure.
+
+## Design Principles
+
+- Keep one recognizable Homarr identity across every surface.
+- Let navigation topology match the task while keeping labels and behavior consistent.
+- Prioritize readable line lengths, strong heading hierarchy, and visible document structure.
+- Make primary paths obvious without adding decorative UI.
+- Preserve useful functionality on mobile, keyboard navigation, and reduced-motion settings.
+
+## Accessibility & Inclusion
+
+Target WCAG 2.2 AA. Maintain keyboard access, visible focus states, sufficient contrast, semantic landmarks, touch-friendly controls, responsive layouts, and reduced-motion behavior.
@@ -0,0 +1,6 @@
+Dockerfile
+.dockerignore
+node_modules
+npm-debug.log
+README.md
+.git
@@ -0,0 +1 @@
+* text=auto eol=lf
@@ -0,0 +1,59 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+.idea/
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.bun-cache/
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+/.source/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# vercel
+.vercel
+*.tsbuildinfo
+
+# storybook
+storybook-static
+static/data/configs
+
+# https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
+# Yarn v2
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# docusaurus
+.docusaurus
+
+# CI Stuff
+screenshots
+test-results
@@ -0,0 +1,30 @@
+{
+  "$schema": "../../node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "typescript", "unicorn", "oxc", "react", "import", "jsx-a11y"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "pedantic": "off",
+    "perf": "off",
+    "style": "off",
+    "restriction": "off",
+    "nursery": "off"
+  },
+  "rules": {
+    "eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
+    "typescript/consistent-type-imports": "off",
+    "typescript/no-non-null-assertion": "warn",
+    "import/consistent-type-specifier-style": "off",
+    "jsx-a11y/alt-text": "warn",
+    "jsx-a11y/control-has-associated-label": "warn",
+    "jsx-a11y/prefer-tag-over-role": "warn",
+    "react/jsx-key": "warn",
+    "react/react-in-jsx-scope": "off",
+    "react-hooks/exhaustive-deps": "warn",
+    "eslint/no-unused-expressions": "warn"
+  },
+  "ignorePatterns": ["**/*.config.js", "**/*.config.mjs", "**/*.cjs", ".docusaurus/**", "build/**"],
+  "settings": {
+    "react": { "version": "19" }
+  }
+}
@@ -0,0 +1,3 @@
+{
+  "cSpell.words": ["Homarr", "Lidarr", "Nextcloud", "Radarr", "Readarr", "Sonarr"]
+}
@@ -0,0 +1,18 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->
+
+## Fumadocs workflow
+
+- Start with `README.md`, `src/lib/source.ts`, `source.config.ts`, and the matching route under `src/app/`.
+- Read current [Fumadocs documentation](https://fumadocs.dev/docs) with Context7 before changing framework APIs. Check the installed version and types; latest examples may use a different search adapter.
+- Preserve static export: search uses `staticGET` with the matching static client. Do not introduce a request-time search server into this app.
+- Keep integration/widget metadata in the existing typed definitions. Check both rendered HTML and processed Markdown when changing MDX components; JSX alone does not guarantee readable search or AI output.
+- Run the README validation commands after content or navigation changes. Search results and table-of-contents links must resolve to rendered anchors.
+- Kapa is an independent hosted assistant. Keep its keyboard shortcut disabled so it does not override docs search; follow the README for its build configuration and crawler setup.
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2025 Meier Lukas, Thomas Camlong and Homarr Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
@@ -0,0 +1,37 @@
+# Homarr Documentation
+
+## Register
+
+product
+
+## Users
+
+People who run Homarr, administrators configuring self-hosted infrastructure, and contributors extending Homarr. They arrive with a concrete task such as installing Homarr, connecting a service, configuring a widget, managing users, or building a custom widget, and need an answer they can scan and apply quickly.
+
+## Product Purpose
+
+The documentation is the complete, authoritative operating guide for Homarr. It keeps setup steps, configuration contracts, screenshots, generated integration and widget metadata, API references, and Workshop tooling next to the application code. Success means a reader can find the right page quickly, understand the next action, copy reliable instructions, and verify the result without searching elsewhere.
+
+## Brand Personality
+
+Focused, dependable, and approachable. The writing is direct and practical. The interface should feel calm and familiar during long technical sessions while retaining Homarr's red identity.
+
+## Anti-references
+
+- Generic marketing layouts that replace Homarr's product identity with unrelated slogans or decorative conversion copy.
+- Decorative dashboard aesthetics that compete with reading, including glass effects, large radii, card grids, and gratuitous motion.
+- Generic generated-docs styling that obscures Homarr's identity or makes navigation feel detached from the main product.
+- Dense reference portals that expose structure without giving readers a clear path through a task.
+
+## Design Principles
+
+1. Put the reader's task first: search, navigation, page outline, and the answer must remain easy to reach.
+2. Preserve one source of truth: typed Homarr metadata and existing custom components stay connected to the monorepo.
+3. Prefer familiar documentation patterns: the interface should disappear while a reader scans, copies, and follows instructions.
+4. Make complete content feel manageable through strong hierarchy, progressive disclosure, and precise cross-links.
+5. Treat machine readers as users through canonical Markdown, structured metadata, and standard LLM discovery endpoints.
+6. Keep the root landing page recognizably Homarr: preserve its self-hosted dashboard promise and real product evidence while documentation routes remain task-first.
+
+## Accessibility & Inclusion
+
+Meet WCAG 2.2 AA for color contrast, keyboard operation, focus visibility, landmarks, headings, and interactive controls. Respect reduced-motion and system color-scheme preferences. Diagrams, screenshots, icons, and emoji must have meaningful text alternatives when they carry information.
@@ -0,0 +1,168 @@
+# Homarr documentation (`@homarr/docs`)
+
+The source for [homarr.dev](https://homarr.dev), built with Next.js and Fumadocs UI inside the Homarr monorepo.
+
+## Develop
+
+From the repository root:
+
+```bash
+bun run dev:docs
+```
+
+The site runs on `http://127.0.0.1:3003`. To use a local Workshop API:
+
+```bash
+WORKSHOP_API_URL=http://127.0.0.1:8090 bun run dev:docs
+```
+
+## Validate
+
+```bash
+bun run --filter @homarr/docs typecheck
+bun run --filter @homarr/docs build
+bun run --filter @homarr/docs validate:links
+bun run --filter @homarr/docs verify:search
+bun run --filter @homarr/docs verify:seo
+```
+
+The static export is written to `out/`. The build validates docs pages and typed metadata for integrations and widgets
+that declare a documentation slug. Set the slug to `null` when a page would add no useful information for advanced users.
+CI enforces coverage alongside schema drift and export validation. The link check validates internal Markdown and MDX
+links and rendered anchors against the export.
+The search check exercises the exported index with title, heading, and body queries and verifies result destinations.
+The SEO check validates canonical URLs, descriptions, social metadata, heading structure, and sitemap coverage in the
+exported HTML. These tags are generated at build time; set `HOMARR_WEBSITE_URL` before building for a different origin.
+
+## Preview the static export with PocketBase
+
+After building the docs, run from the repository root:
+
+```bash
+sh apps/workshop/preview-docs.sh
+```
+
+Open `http://127.0.0.1:8093/docs/`. This starts an isolated PocketBase container with temporary local data and serves
+the export directly, including search, Markdown, and the custom 404 page. Workshop browser requests use the configured
+backend; a trailing `/api/` is removed because the PocketBase SDK appends its API paths. The preview does not copy or
+migrate another database. Set `WORKSHOP_API_URL` to a remote PocketBase origin when testing against one;
+`WORKSHOP_REMOTE_API_URL` can override the server-side metadata source independently. Direct item links then use that
+source for titles and social metadata. Missing remote items return 404; an unavailable backend returns 503.
+
+Verify public item pages without changing the remote database:
+
+```bash
+REMOTE_WORKSHOP_URL=https://workshop.example.com
+WORKSHOP_TEST_URL=http://127.0.0.1:8093 WORKSHOP_REMOTE_API_URL="$REMOTE_WORKSHOP_URL" \
+  bun apps/workshop/tests/remote-workshop.integration.mjs
+```
+
+Stop it with `docker stop homarr-docs-static-preview`. Rebuild and restart the preview after changing source files;
+startup recreates the runtime configuration. `DOCS_PREVIEW_PORT`, `DOCS_PREVIEW_HOST`, and `DOCS_PREVIEW_NAME` override
+the defaults. Set the host to this machine's Tailscale address to access it from your other devices.
+
+## Write content
+
+Documentation lives in `docs/`; project posts live in `blog/`. Navigation is controlled by the nearest `meta.json`.
+Integration and widget folders pair typed `index.ts` metadata with `index.mdx` content.
+
+Use standard Markdown and MDX. Shared components live in `src/components/`. Mermaid fences, tabs, callouts, zoomable
+images, and syntax-highlighted code are supported by the Fumadocs pipeline.
+
+Update docs in the same pull request only when a smart, advanced user cannot infer the changed behavior from the UI or
+generated API schema. Routine or self-explanatory changes need no docs update. See the
+[documentation-sync skill](../../.agents/skills/documentation-sync/SKILL.md) for target paths.
+
+## Published formats
+
+- `/docs` — searchable documentation with typed navigation
+- `/api-reference` — interactive reference generated from the OpenAPI schema
+- `/llms.txt` — compact documentation and blog index for agents
+- `/llms-full.txt` — complete processed Markdown corpus
+- `/llms.mdx/docs/.../content.md` — raw Markdown for each docs page
+- `/llms.mdx/blog/.../content.md` — raw Markdown for each blog post
+- `/llms.mdx/api-reference/.../content.md` — operation parameters, bodies, responses, and authentication
+- `/blog/rss.xml` — RSS feed for project posts
+- `/search?q=...` — opens documentation search with the supplied query, including existing Homarr search-engine links
+
+Every docs page and blog post includes copy-Markdown and view-source actions. Search is generated at build time and
+runs locally in the browser; it does not depend on an external crawler. Markdown exports and search resolve
+integration credentials and widget defaults from the same typed metadata used by the pages.
+The search dialog and its client-side engine load when search is first opened. Fumadocs caches the downloaded index
+for subsequent queries. The docs index, individual Markdown pages, and full corpus share the `llms()` renderer.
+API operations are indexed alongside docs and exported as Markdown from the same OpenAPI schema. The reference uses
+Fumadocs with Scalar: select an instance URL and API key, then explicitly send a request. Authentication is not
+persisted in local storage. Browser access requires the documented REST CORS configuration.
+
+The Custom JSX guide includes a lazily loaded, editable example using the application renderer and real component
+registry. Its bindings work locally; configured widget queries and actions do not run.
+
+The getting-started overview and complete Custom JSX component catalog are also included, with property types,
+binding contracts, and blocked capabilities taken from the published catalog JSON.
+
+Published Docusaurus `/docs/category/...` addresses remain available as static compatibility pages. They forward to
+the corresponding overview or developer setup guide, preserving query strings and anchors, and provide a direct
+link when JavaScript is disabled. Their canonical metadata points to the destination; compatibility pages are
+excluded from search and the sitemap.
+
+## Fumadocs upgrade notes
+
+The September 2026 update moves Core/UI from 16.15.4 to 16.15.12, MDX from 15.4.0 to 15.4.3, and OpenAPI from
+11.3.5 to 12.0.1. Review the upstream [Core](https://github.com/fuma-nama/fumadocs/blob/dev/packages/core/CHANGELOG.md),
+[UI](https://github.com/fuma-nama/fumadocs/blob/dev/packages/radix-ui/CHANGELOG.md),
+[MDX](https://github.com/fuma-nama/fumadocs/blob/dev/packages/mdx/CHANGELOG.md), and
+[OpenAPI](https://github.com/fuma-nama/fumadocs/blob/dev/packages/openapi/CHANGELOG.md) changelogs when upgrading.
+
+- Core/UI and MDX now declare side effects for better tree shaking. UI also fixes tabs reverting to the URL hash.
+- Core's `llms({ renderPage })` API provides the shared `index()`, `page()`, and `full()` exports.
+- OpenAPI 12 replaces several custom renderer options and hooks. This site uses `createOpenAPIPage()` and
+  `getOpenAPIPageProps()` without those removed overrides; the built-in renderer retains all request languages.
+  The Scalar adapter receives an equivalent nonrecursive union for unconstrained JSON values to avoid recursive
+  schema expansion during rendering. The generated public OpenAPI document remains unchanged.
+- MDX 15.4.3 fixes duplicate compilation output when its experimental build cache is enabled. We leave that cache
+  disabled: its current key checks source content without accounting for all compiler configuration changes.
+- The existing macro collections, processed-Markdown component adapters, and static search remain supported.
+  Typed version roots and server-side MCP tools are available upstream but are not needed by this static site.
+
+## Kapa AI
+
+The compact Homarr mascot in the bottom-right opens **Ask AI**. It slowly spins when idle and gives a subtle claw movement and wink on hover. Animation respects reduced motion.
+
+The launcher uses Homarr's existing public Kapa Website ID. The root layout loads the widget once across
+client-side navigation and follows the docs light or dark theme. **Search** and `Ctrl+K` / `Cmd+K` always use Fumadocs search, including when Kapa is unavailable.
+
+Set `KAPA_WEBSITE_ID` at build time to use a different Kapa Website Widget integration. An explicitly empty value
+disables the widget, for example `KAPA_WEBSITE_ID= bun run --filter @homarr/docs build`. This is a public integration ID
+included in exported pages, not a Kapa API key. Rebuild the static export after changing it.
+
+In the Kapa dashboard, confirm the integration is live and enable the production and preview domains. Restoring the
+script does not verify that the historical integration is still active. Follow the
+[Kapa widget setup](https://docs.kapa.ai/integrations/website-widget/quickstart) for domain restrictions and CSP settings.
+
+After changing the documentation structure, review the Website Crawl source in Kapa: use the deployed `/docs` URL as
+the start URL and preview `main` as the content selector. Replace any old Docusaurus-specific selector and check that
+titles, headings, code samples, and integration details appear in the extracted Markdown. Docs are exported as HTML;
+the site also publishes `/sitemap.xml` and permits crawling in `/robots.txt`. The `/llms.txt` exports do not configure
+Kapa ingestion automatically. See [Kapa source setup](https://docs.kapa.ai/getting-started/index-your-first-source).
+
+Before publishing, check that Ask AI opens after navigating between pages, ask a documentation question, and verify
+its citations point to the current docs. In a separate check, block `widget.kapa.ai` and confirm search still works.
+
+## Release verification
+
+The production image compiles the docs itself; it does not depend on a host `out/` directory.
+Build-time `HOMARR_WEBSITE_URL` controls canonical metadata. Runtime URL overrides configure Workshop connections
+but do not rewrite already-exported canonical URLs.
+
+PostHog records SPA pageviews, installation clicks, searches with no results (including the search query), and Workshop
+content downloads and submission starts/completions through `hog.homarr.dev`. Downloads include JSON files and
+successful JSON/CSS clipboard copies. All events carry `site` and `source_path`. Autocapture, page-leave events, and
+session replay are disabled; tracked URL query strings and fragments are removed. Localhost and `?analytics_test`
+traffic carries `verification=true`; exclude it from production reports.
+
+Carbon loads one visible placement after the desktop TOC, below API examples, or below content on other layouts.
+The homepage is excluded at every viewport size. Navigation reloads the ad script; resizing changes placement only when crossing its breakpoint. Ad blockers
+or no-fill responses must not prevent content, navigation, or search from working.
+
+To preview Carbon locally, start docs with `NEXT_PUBLIC_ENABLE_CARBON_ADS=true bun run dev:docs`. Production builds
+enable ads automatically. When the TOC collapses into a toggle, the ad appears below the content before “Edit this page”.
@@ -0,0 +1,36 @@
+---
+slug: documentation-migration
+title: Migration of Documentation
+date: 2022-06-22
+authors:
+  - ajnart
+  - manuel-rw
+tags: [documentation, migration]
+---
+
+We are happy to announce that the documentation of Homarr has been migrated to Docusaurus - An opensource documentation tool.
+The documentation has been re-written partly and includes now many animations, guides and additional crucial information.
+
+We are still figuring things out and highly depend on your feedback.
+
+{/* Historical excerpt boundary. */}
+
+## Why we migrated
+
+The default GitHub Wiki feature is decent - but very confusing to read.
+Our possibilites for searching the documentation in the Wiki are highly limited.
+Additionally, Users are unable to contribute to the documentation if they have not sufficient permissions.
+
+We could not review any chanegs made to the documentation. This is why we migrated to Docusaurus.
+
+## How you can contribute
+
+The documentation will soon be merged into the master branch of Homarr.
+You'll find a ``doc/`` directory in the root of Homarr.
+We'll obviously not include this in our Docker images.
+In the future, everyone may modify the documentation by creating a pull request.
+After we've reviewed your changes, we'll merge your PR and this documentation will automatically update.
+
+## TL;DR
+
+The documentation on GitHub Wiki will soon disappear. It will be replaced with this Docusaurus-powered website. You'll find much more information here with higher detail and searchability.
@@ -0,0 +1,21 @@
+---
+slug: translations
+title: Help us make Homarr multilingual
+date: 2022-08-28
+authors:
+  - ajnart
+  - manuel-rw
+tags: [translations, homarr, update, contributions]
+---
+
+We've been working hard to offer Homarr in many languages. The next update of Homarr will be using [i18next](https://www.i18next.com/) to translate almost any part of your Dashboard.
+
+### We need your help
+![](img/homarr-we-need-you.webp) <br/>
+Yes, we need **YOU**! We want to make Homarr accessible to as many people as possible. Thus, we need to translate all content into many different languages. We need your help for that! [You can help us now to translate Homarr into as many languages as possible](/docs/community/translations).
+
+{/* Historical excerpt boundary. */}
+
+### About global translations / translations per user
+
+We are aware that many people would like to configure translations globally or configure language per user. Currently, translations are stored in the Cookies, which will expire after some time (currently, it's set to 30 days). We will implement more granular language settings in future versions of Homarr, since it requires major changes to Homarr. Stay tuned! 😎
@@ -0,0 +1,68 @@
+---
+title: "We present: Homarr 0.11 - the most complex Homarr version yet!"
+date: 2023-01-11
+authors:
+  - ajnart
+  - manuel-rw
+  - walkx
+  - meierschlumpf
+tags: [homarr, update, breaking changes, version, gridstack, dnd, documentation]
+---
+
+We are *incredibly* proud to serve you Homarr 0.11!
+It contains many breaking changes and huge improvements to your favourite dashboard app:
+
+- Integration of Gridstack for much more complex dashboard configuration and drag and drop
+- Added icon picker with smart search and automatic icons
+- Complete overhaul of the module system
+- Added an edit mode for making changes easier
+- Form validation for better user experience
+- Better security with new built-in credentials system
+- Huge design and usability improvements to older components to Homarr
+- Better handeling of exceptions and unexpected issues
+
+{/* Historical excerpt boundary. */}
+
+## Complete implementation of highly customizable drag and drop library "Gridstack"
+
+In 0.11, we have replaced our quite limited drag and drop system with Gridstack.
+Gridstack enables you to create much more complex and advanced dashboards while keeping everything organized.
+
+<video style={{ maxWidth: "min(100%, 600px)", borderRadius: "0.5rem"}} controls preload='auto' autoplay >
+  <source src="https://user-images.githubusercontent.com/30572287/217098893-5880e7de-13d0-42c5-b505-f7921593396f.mp4" type="video/mp4" />
+    <p>
+      To view this video please enable JavaScript, and consider upgrading to a
+      web browser that
+      <a href="https://videojs.com/html5-video-support/" target="_blank">
+        supports HTML5 video
+      </a>
+  </p>
+</video>
+
+We've also introduced more advanced categories this time:
+
+![](../../../docs/getting-started/img/category-menu.webp)
+
+We'll continute to improve this system according to your feedback.
+
+## Modules have been overhauled and renamed to widgets
+
+Widgets are now much snappier and have been completely recoded.
+This fixes some of the bugs a few users have previously experienced and improves overall customization.
+
+![](./img/choose-widget-in-modal.webp)
+
+## Fancy icon picker for speeding up your creation process
+
+We've also added a new fancy icon picker, you can use to get access to any icons much faster.
+We will add more icon sources in the future, as we made this icon picker very modular, and we plan to make local icons accessible via this picker very soon.
+
+![](../../../docs/advanced/customizations/img/icons/icons-picker.gif)
+
+## Design and documentation improvements to homarr.dev
+
+https://homarr.dev has been overhauled with better design, updated documentation, more images and better explanations.
+
+## Download Homarr now!
+
+Homarr is completly free, even for commercial usage!
@@ -0,0 +1,74 @@
+---
+title: "We present: Homarr 0.12 - The fastest homarr version ever!"
+date: 2023-04-16
+authors:
+  - ajnart
+  - manuel-rw
+  - walkx
+  - meierschlumpf
+tags: [homarr, update, breaking changes, version, dnd, documentation]
+---
+
+## Multiple widgets of the same type
+**It's finally here!** You can decorate your dashboard now with as many widgets as you want.
+This applies to all widgets, but in the case of the IFrame widget, it enables you to:
+- Integrate as many websites as you want
+- Integrate monitoring tools like Grafana, Splunk or Elasticsearch
+- Integrate your services (for example Sonarr, Radarr and Overseerr) directly into Homarr
+
+## Edit mode password
+We've added a setting to disable editing completely. This will allow you to restrict edit access without password-protection.
+use the `EDIT_MODE_PASSWORD` ENV variable to set a password for edit mode. 
+turn on `DISABLE_EDIT_MODE=TRUE` to disable edit mode on startup.
+
+{/* Historical excerpt boundary. */}
+
+## 😎 Blazingly fast
+We've implemented a new caching system, that will cache all data in your browser, meaning that Homarr will load within milliseconds, as if it was *powered by rust and blazingly fast* !!!
+
+## Media request widgets (Overseerr & Jellyseerr)
+We've implemented a new widget, that displays a history of all requests.
+You can't approve from the widget yet, but we plan to add this in the future.
+
+![image](https://user-images.githubusercontent.com/30572287/231829411-f61f03e9-79a0-45fc-9a87-94d69ea3ea84.png)
+
+## Multiple RSS feeds
+You can now consume multiple RSS feeds at the same time:
+
+![image](https://user-images.githubusercontent.com/30572287/231829886-69133a84-3ae7-4fa3-a6d2-c582f4cc9eea.png)
+
+## Tab refresh / close confirmation
+Since some have lost their changes, by refreshing the page in the edit mode. We've added a popup that will ask you to confirm you want to reload the page :
+
+![image](https://user-images.githubusercontent.com/30572287/231823776-9cbb12d4-3cb3-422e-b2e8-f9917bb3f8cc.png)
+
+## Environment variable for default theme
+You can now set the default color scheme using environment variables:
+
+``DEFAULT_COLOR_SCHEME`` = ``[dark, light]``
+
+## Global error catching for widgets
+Previously, widgets were able to crash your entire dashboard and just a blank page would be displayed.
+Now, users will still be able to use their dashboard and an information message will be displayed instead.
+
+## Migration to Mantine V6
+We've migrated Mantine to version 6. This will bring some upstream changes for responsiveness and usability.
+
+## Fix width and height in the calendar
+In 0.11.5 and previous versions, the calendar scaled poorly if the widget was resized.
+Now, the calendar will fill out the entire available space and scale nicely with your dashboard.
+
+![](https://cdn.discordapp.com/attachments/988335098493542410/1095416419816067175/homarr-calendar-scaling.gif)
+
+## Performance improvements
+We now use several methods to improve performance and reduce network requests.
+Homarr will load now within milliseconds and cache data in your browser.
+
+## Docker Socket via TCP
+Previously, it was not possible to mount sockets via TCP (eg. ``tcp://traefik-docker-socket-proxy:2375``).
+Now, you can use the following environment variables to configure this:
+
+- ``DOCKER_HOST``
+- ``DOCKER_PORT``
+
+**Full Changelog**: https://github.com/ajnart/homarr/compare/v0.11.5...v0.12.0
@@ -0,0 +1,87 @@
+---
+title: "Authentication in Homarr - 0.14 is here!"
+date: 2023-11-10
+authors:
+  - ajnart
+  - manuel-rw
+  - tagashi
+  - meierschlumpf
+tags: [homarr, update, breaking changes, version, authentication, notepad, security]
+---
+
+One of the most requested features ever has arrived.
+We worked for months to prepare Homarr for this update and we're happy that we can finally
+provide you a viable solution today.
+
+## Highlights at a glance
+
+- :rocket: Completly overhauled authentication system with user management
+- :sparkles: Improved UI for boards (renamed dashboards to boards).
+- :computer: Server side preferences -> Dark mode and language are not synced accross all your devices
+- :link: Invitation links to easily onboard new users
+- :busts_in_silhouette: Overhauled board management with easy control if anonymous users can view your board
+- :brain:  AI assistant on the documentation to answer your questions: https://homarr.dev/
+- 📝 Overhauled notepad widget with a complex graphical editor that enables easy editing right from your browser.
+- :globe_with_meridians:  Live Translation on Crowdin that enable you to directly translate using images to see what exactly you're translating
+
+{/* Historical excerpt boundary. */}
+
+## Breaking changes
+
+- Removed ``PASSWORD`` environment variable
+- Removed ``DISABLE_EDIT_MODE`` environment variable
+- Removed ``EDIT_MODE_PASSWORD`` environment variable
+- Added mounting point ``/data`` for your database
+- Require at least one administrator account on your instance. An onboarding process will automatically set this up.
+- We've added analytics to the documentation and Homarr itself. We use [Umami Analytics](https://umami.is/) which collects anonymous data exclusively and protects your personal data rights. You can disable this using the environment variable ``DISABLE_ANALYTICS``.
+
+## Changes in detail
+
+### Management pages
+![image](https://github.com/ajnart/homarr/assets/30572287/b325eb92-57a6-4b07-a281-f10f7471642e)
+One of the most requested features ever has been ___authentication___. We've completely *removed* the ``PASSWORD``, ``DISABLE_EDIT_MODE`` and ``EDIT_MODE_PASSWORD`` and replaced it by [a secure authentication system](https://next-auth.js.org/) that enables you to manage multiple users easily. We will allow for more detailed permission and user management soon. LDAP and OIDC integrations are currently also in progress and will arrive in a future version.
+
+### New dashboard layout
+![image](https://github.com/ajnart/homarr/assets/30572287/3396da13-816a-434f-a4c1-0efc7f86154c)
+
+We've updated the dashboard user interface slightly to an updated design.
+
+### Server side preferences page
+![image](https://github.com/ajnart/homarr/assets/30572287/2c1f4dbe-7aa7-4c56-aaa3-d6c49e2beeec)
+
+Previously, preferences were stored per dashboard and applied to all users.
+In this release, we moved this page to a separate link and store this on the server.
+This means that regardless what device your on - your preferences will stay the same when you're logged in.
+
+### Invitations for new users
+![image](https://github.com/ajnart/homarr/assets/30572287/a929b345-c014-48fb-aef9-ea2c3c581376)
+
+Tired of creating user accounts by yourself? With the new "invites" feature you can invite new users by simply sending them a link.
+This link is valid only once and must have an expiration date - more info on that in our documentation.
+
+Additionally, you can deny users, that are not logged into an account, to access your board with a simple toggle:
+
+![image](https://github.com/ajnart/homarr/assets/30572287/aa3ff3fb-66fc-4f88-93fb-b2dd819599a8)
+
+### New "boards" page
+Previously, dashboards were managed in an ugly and hard to control popup.
+We've moved this now to the new management pages as well and it's now much easier to control:
+
+![image](https://github.com/ajnart/homarr/assets/30572287/2b24222e-da33-45eb-a54f-89a33a21881d)
+
+
+### Read-only for non-administrators and guests
+Yes, managing access to your dashboard is now much easier!
+Guests and non-administrators cannot edit your dashboard in any way (edit is hidden):
+
+![image](https://github.com/ajnart/homarr/assets/30572287/01c48beb-5453-4626-ac4d-f8d7177e999b)
+
+This is not an definite solution and will be significantly improved in an upcoming update.
+
+-----
+
+We are aware that this update has many breaking changes and may confuse some users.
+For that reason, we updated our documentation and will enhance it further within the next few weeks.
+We've also added this small button at the bottom of the page were you can ask **your questions** to an AI assistant:
+
+![image](https://github.com/ajnart/homarr/assets/30572287/a56f721a-d022-42ad-813a-d85c89462a8c)
@@ -0,0 +1,22 @@
+---
+title: "Updated documentation with better organization & design"
+date: 2023-12-22
+authors:
+  - manuel-rw
+tags: [homarr, documentation, design, docs]
+---
+
+We'd like to let you know that we've updated our documentation and reorganized the pages.
+This means, that some links may no longer be valid - we apologise if this causes any inconvenience for you.
+
+{/* Historical excerpt boundary. */}
+
+A few highlights include:
+
+- Updated navigation bar for much easier navigation
+- Improvements to the landing page
+- Completely revamped [about us page.](/about-us)
+- Bug fixes for image zoom
+- Added documentation for management pages and [new CLI tool](/docs/advanced/command-line/password-recovery/)
+
+Please [let us know](/docs/community/get-in-touch) is something is not working as expected.
@@ -0,0 +1,87 @@
+---
+title: Homarr 1.0 - complete rewrite of all systems
+date: 2024-09-23
+authors:
+  - manuel-rw
+---
+
+We proudly present to you - Homarr ``1.0``.
+We have started work on this new version back in 2023 and have worked tirelessly for months on this brand-new dashboard.
+
+This isn't our usual update. ``1.0`` doesn't use the same code from previous versions, but has been written from the ground up.
+Therefore, this version contains an unusual amount of breaking changes.
+This will be a one time occurrence and version > ``1.0`` will have less breaking changes.
+This time more important than every; **read the breaking changes** list and **create a backup** before updating.
+Some third party installation methods may take multiple days or weeks to update to the new version.
+
+## Changes at a glance
+- **Asynchronous integrations system**: In versions prior to ``1.0``, we fetched data upon each request synchronously.
+This means that the user had to wait for the requests to finish so any data would appear.
+A page reload will trigger another request - and worse, this will happen for every user accessing your dashboard.
+In ``1.0``, we have implemented a new system that gets rid of this system and scales linearly.
+It will fetch data in background, even if you are not on the page.
+- **Permissions system**: You can now use detailed permissions to allow or prohibit users from certain actions.
+For easier management, you can organize users into groups and manage them all at the same time.
+- **Integration testing**: Starting from ``1.0``, we will require you to test the integration before you can use it.
+This guarantees that you've configured your integration correctly and helps you find errors faster.
+- **Re-imagined widgets**: All widgets have been rewritten & improved. They offer much better performance,
+reliability and scalability compared to < ``1.0``.
+- **Improved performance**: We have upgraded the underlying framework of Homarr and take advantage
+of an in-memory message bus and websockets to deliver data near realtime to you.
+
+{/* Historical excerpt boundary. */}
+
+## Breaking changes
+<Alert type="warning">
+
+Please consult the breaking changes list & upgrade guide if you used third-party installation methods.
+
+</Alert>
+
+- Docker Image
+  - Removed support for ``arm/v7`` -> upgrade to newer architectures as an alternative
+  - Renamed image from ``ghcr.io/ajnart/homarr`` to ``ghcr.io/homarr-labs/homarr``. We now use semantic versioning for our release numbers.
+- Environment Variables
+  - New required env variable ``SECRET_ENCRYPTION_KEY`` used for encryption of secrets in the database
+  - Removed ``DISABLE_ANALYTICS``, can now be configured via UI
+  - Renamed ``AUTH_PROVIDER`` to ``AUTH_PROVIDERS``
+  - Renamed ``DATABASE_URL`` to ``DB_URL`` and made it optional conditionally. If ``DB_HOST`` is set, this is optional - otherwise it's required.
+  - Changed ``DOCKER_HOST`` to two new variables for hostnames (``DOCKER_HOSTNAMES``) and ports (``DOCKER_PORTS``). This allows for multiple docker integrations to be configured.
+  - ``AUTH_LOGOUT_REDIRECT_URL`` must now be a valid Url
+  - Increased minimum length of ``AUTH_OIDC_CLIENT_ID`` to 1
+  - Increased minimum length of ``AUTH_OIDC_CLIENT_SECRET`` to 1
+  - Removed ``AUTH_OIDC_TIMEOUT``
+  - Removed ``AUTH_LDAP_ADMIN_GROUP``, ``AUTH_LDAP_OWNER_GROUP``, ``AUTH_OIDC_ADMIN_GROUP`` and ``AUTH_OIDC_OWNER_GROUP`` -> groups are now managed without manual env binding
+  - ``CI`` will now also trigger an env validation skip like ``SKIP_ENV_VALIDATION``
+- Mounts
+  - Removed ``/app/data/configs`` -> JSON configs have been removed in favour of relation databases
+  - Removed ``/app/public/icons`` -> Images can not be uploaded via the [media management](/docs/management/media/) in the UI
+  - Moved ``/data`` to ``/appdata`` and restructured contents (not backwards compatible!) -> Create a backup before migration of the entire directory to copy data to new Homarr
+- Widgets:
+  - Calendar:
+    - Removed option ``Use Sonarr v4 API``
+    - Removed option ``Use Sonarr v5 API``
+    - Removed option ``Font Size``
+    - Removed option ``Hide week days``
+  - Download speed: We have removed this widget in favour of the brand new download widget which will also display this data.
+  - Dash. widget: We have removed this widget in favour of the System Health Widget. It will also display all data and some more than the old widget.
+- Database:
+  - Changed schema of the database to a completely new schema. They are not backwards compatible. Please export the data from old Homarr in the UI and import it in ``1.0``
+  - Removed all usage of JSON files to store data. Import JSON files in Homarr ``1.0`` to import your dashboards.
+  - Removed ``schemaVersion`` from JSON and use the drizzle migrations to keep track of schema versions and take care of migrations.
+- Web Server:
+  - Added an internal Nginx proxy to forward requests to two servers inside the container for technical reasons.
+  This could impact edge cases with iframes, cookies and custom setups.
+- Dependencies
+  - We now depend on [Redis](https://redis.io/) as a real time messaging bus
+- Development (relevant for contributors):
+  - Migrated to [pnpm](https://pnpm.io/)
+  - Migrated to a mono-repository
+  - All source code has been migrated to the [homarr-labs GitHub organization](https://github.com/homarr-labs)
+- Platform specific breaking changes:
+  - TrueNAS
+    - The TrueCharts app chart is permanently deprecated and no longer maintained / supported. Please migrate to Electric Eel or a different Kubernetes platform.
+  - Unraid
+    - The Homarr app must be reinstalled. The existing directories on your disk are not compatible with Homarr 1.0. Export your old data in < `` 1.0`` and install using different file system locations.
+  - Kubernetes
+    - The official Helm chart has moved from https://github.com/oben01/charts to https://github.com/homarr-labs/charts
@@ -0,0 +1,39 @@
+---
+title: Open Beta 1.0
+date: 2024-12-17
+authors:
+  - meierschlumpf
+---
+
+We are proud to announce the open beta of Homarr 1.0. This is a major milestone for us and we are excited to share it with you.
+The open beta allows us to polish the last rough edges and gather feedback from you.
+We are looking forward to your feedback and hope you enjoy the new features.
+Let us know throgh discord or a [github issues](https://github.com/homarr-labs/homarr/issues/new/choose) if you encounter any issues.
+
+{/* Historical excerpt boundary. */}
+
+## How to use the beta with docker
+
+To use the beta with docker you can use the following docker-compose.yml configuration:
+
+```yml title="docker-compose.yml"
+#---------------------------------------------------------------------#
+#     Homarr - A simple, yet powerful dashboard for your server.      #
+#---------------------------------------------------------------------#
+services:
+  homarr:
+    container_name: homarr
+    image: ghcr.io/homarr-labs/homarr:beta
+    restart: unless-stopped
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration
+      - ./homarr/appdata:/appdata
+    environment:
+      - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
+    ports:
+      - '7575:7575'
+```
+
+Then, run `docker compose up -d` in the same directory. This will start the Homarr container in the background.
+Please note that the mounts have changed and it's not backwards compatible with versions before 1.0.0-beta.1.
+You can find a list of all breaking changes [here](/blog/2024/09/23/version-1.0)
@@ -1 +1 @@
 .21.0
 .18.0