feat: unify Workshop experience

2026-07-14 01:21:53 +02:00
1 parent 066090d99e
commit 9f979f683a
@@ -67,15 +67,19 @@ UNSAFE_ENABLE_MOCK_INTEGRATION=true
 # Whether demo mode is read-only. Defaults to true (the public demo blocks all mutations).
 # Set to false for writable preview deployments so the demo user can modify the dashboard.
 # DEMO_READ_ONLY=false
-# Central Homarr Workshop API. Override only when developing the Workshop locally.
+# Central Workshop API is https://homarr.dev. Override only when developing
+# the standalone Docusaurus or Homarr clients against a local backend.
 # NEXT_PUBLIC_WORKSHOP_API_URL=http://localhost:8090
 # WORKSHOP_API_URL=http://localhost:8090

-# Workshop development backend and GitHub OAuth.
+# Workshop development service and GitHub OAuth.
 # The GitHub OAuth callback URL is http://localhost:8090/api/oauth2-redirect.
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 PB_SUPERUSER_EMAIL=
 PB_SUPERUSER_PASSWORD=
 PB_EXPOSE_PORT=8090
-PB_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:3003,http://127.0.0.1:3003,http://localhost:7575,http://127.0.0.1:7575
+PB_PUBLIC_URL=http://localhost:8090
+# Workshop is intentionally consumable by arbitrary self-hosted Homarr origins.
+# PocketBase is stateless and authorizes writes with bearer tokens, not cookies.
+PB_ALLOWED_ORIGINS=*
@@ -1,56 +0,0 @@
-name: "[Deployment] Documentation"
-
-on:
-  push:
-    branches: ["dev"]
-    paths:
-      - "apps/docs/**"
-      - "packages/definitions/src/docs/**"
-      - ".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
-      - name: Build docs
-        run: pnpm turbo build --filter=@homarr/docs
-        env:
-          CI: "true"
-      - name: Setup Pages
-        uses: actions/configure-pages@v6
-      - name: Upload pages artifact
-        uses: actions/upload-pages-artifact@v5
-        with:
-          path: "apps/docs/build"
-
-  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
@@ -0,0 +1,53 @@
+name: "[Deployment] Workshop"
+
+on:
+  push:
+    branches: ["dev"]
+    paths:
+      - "apps/docs/**"
+      - "apps/workshop/**"
+      - "packages/definitions/src/docs/**"
+      - "packages/validation/**"
+      - "packages/workshop/**"
+      - "patches/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".github/workflows/deployment-workshop.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: workshop-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+      - name: Build and publish Workshop
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: apps/workshop/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/homarr-labs/workshop:dev
+            ghcr.io/homarr-labs/workshop:sha-${{ github.sha }}
+          cache-from: type=gha,scope=workshop
+          cache-to: type=gha,mode=max,scope=workshop
@@ -0,0 +1,87 @@
+---
+score: 9
+p0: 0
+p1: 1
+timestamp: 2026-07-13T21-26-11Z
+slug: apps-docs-src-components-workshop
+---
+# Workshop V2 audit
+
+## Purpose
+
+The Workshop is Homarr's central community catalog for custom widgets and CSS themes. It must let people discover, inspect, export, publish, update, report, and install creations from homarr.dev and from Homarr itself without requiring raw copy-and-paste as the default workflow.
+
+### Feature North Star
+
+A Homarr user can move from a useful local creation to a safe community submission, or from a community listing to an installed local creation, in one understandable flow with source visibility and an explicit confirmation boundary.
+
+### Developer-experience North Star
+
+Workshop behavior is defined once: one typed contract, one client, versioned PocketBase migrations, deterministic local startup, shared validation fixtures, typed failures, and UI components that contain presentation rather than PocketBase queries or authorization rules.
+
+## Baseline audit
+
+The abandoned prototype is preserved at `origin/feat/widget-store-prototype-backup` (`89260b875`). This rewrite starts at `dev` commit `ba7718bde`.
+
+| Area          | Severity | Baseline finding                                                                                                                    | V2 resolution                                                                                                      |
+| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Branch health | P0       | PR #5984 was based on an obsolete `dev` commit and conflicted with the current branch.                                              | Rebuild from current `dev`; keep the old head on a backup ref.                                                     |
+| Security      | P0       | Submission validation ran in browsers and could be bypassed with direct PocketBase writes.                                          | Enforce validation, ownership, account state, immutable fields, and upload limits in PocketBase hooks and rules.   |
+| Moderation    | P0       | There were no moderator roles, posting bans, disabled accounts, least-privilege actions, or durable moderation history.             | Add roles, account states, explicit moderation routes, a staff UI, and append-only actions.                        |
+| Architecture  | P1       | Docs and Next.js defined separate record types, queries, mutations, sorting, voting, and error behavior.                            | Add `@homarr/workshop` as the only public contract and API client.                                                 |
+| Performance   | P1       | The browser downloaded every submission and full content, then searched, sorted, and filtered locally.                              | Server-side pagination/filtering/sorting; summary views exclude content.                                           |
+| Product       | P1       | Website and app flows were disconnected and sharing still depended on manual content transfer.                                      | Add contextual install and direct share actions backed by canonical exports.                                       |
+| UX/UI         | P1       | A large bespoke Docusaurus component set and a separate Mantine modal produced inconsistent interaction and state behavior.         | Use each host's native components with shared flows, copy rules, contracts, and states.                            |
+| Accessibility | P1       | Several custom interactive elements bypassed semantic controls and touch targets; focus and reduced-motion behavior was incomplete. | Require semantic controls, visible focus, keyboard operation, 44px touch targets, AA contrast, and reduced motion. |
+| Operations    | P1       | A third-party PocketBase image and incomplete bootstrap docs made builds and recovery non-deterministic.                            | Build a pinned official binary with checksum verification; document health, backup, restore, OAuth, and upgrades.  |
+| Testing       | P1       | Tests covered a narrow client schema and did not exercise API rules, roles, auth states, moderation, or cross-surface flows.        | Add contract, backend permission-matrix, UI, and end-to-end coverage.                                              |
+| Documentation | P2       | Documentation advertised a supported self-hosted Workshop even though V2 is a central Homarr service.                               | Document the central service and local-development overrides only.                                                 |
+
+## Decisions
+
+- Public name: **Workshop**.
+- Launch content: custom widgets (`homarr-custom-widget-v2`) and CSS (`homarr-custom-css-v1`).
+- Identity: GitHub OAuth only.
+- Community features: votes and reports; comments are removed.
+- Hosting: one Homarr-operated image and origin at `homarr.dev`; PocketBase serves both compiled docs and `/api`.
+- Resilience: the public shell and successfully loaded query data are cached independently; the rest of Homarr never depends on Workshop availability.
+- Publishing: immediate, with source inspection, reporting, and staff removal.
+- Staff: GitHub-authenticated moderators/admins use `/workshop/admin`; PocketBase superusers are bootstrap/emergency access.
+
+## Launch acceptance
+
+- [x] Anonymous users can browse, search, filter, inspect, copy, and download without receiving full content in listing responses.
+- [x] Members can publish, update, delete, vote, and report; ownership and schemas are enforced server-side.
+- [x] Posting-banned users cannot create or update submissions but can browse, vote, and report.
+- [x] Disabled accounts cannot authenticate or write, including with an existing token.
+- [x] Moderators can resolve reports, remove submissions, posting-ban users, and disable/restore non-admin users.
+- [x] Only admins can change roles; staff actions are append-only and attributable.
+- [x] Homarr can export/share local widgets and CSS and validate/confirm Workshop installs.
+- [x] Website and app implement loading, empty, offline, validation, permission, and destructive-action states.
+- [x] Keyboard semantics, mobile layout, dark mode, reduced motion, and horizontal overflow received a browser smoke test.
+- [x] Clean PocketBase startup, migration, health, backup, and restore procedures are reproducible and documented.
+- [x] Documentation and Workshop API are built into one reproducible image and served from `homarr.dev` without production cross-origin requests.
+- [ ] Add automated authenticated cross-surface E2E coverage before changing the PR from draft to ready.
+
+## Deferred after V2
+
+Comments, private Workshop deployments, automated approval queues, follows, collections, notifications, arbitrary package types, historical version installation, and personalized recommendations.
+
+## Exit scorecard
+
+The baseline has three P0, seven P1, and one P2 findings. The rewrite closes every product, security, architecture, moderation, performance, operations, documentation, UX, and DX finding. One P1 release-verification item remains: automated authenticated E2E across both public and in-app surfaces. Keep PR #5984 in draft until it lands.
+
+| Gate                        | Result  | Evidence                                                                                                                                                                                          |
+| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Branch ancestry             | Pass    | Rebuilt from `dev` at `ba7718bde`; prototype preserved at `origin/feat/widget-store-prototype-backup`.                                                                                            |
+| Contract                    | Pass    | Five Vitest cases cover widget/CSS fixtures, filenames, limits, screenshot validation, and round trips.                                                                                           |
+| Backend                     | Pass    | Disposable PocketBase integration matrix covers roles, account states, ownership forgery, schema rejection, duplicate votes, private reports, escalation, deletion cascades, and audit snapshots. |
+| Backend operations          | Pass    | PocketBase 0.39.6 runs unprivileged and builds with checksum verification; clean boot and a cloned legacy SQLite volume both migrate and become healthy.                                          |
+| Type safety                 | Pass    | Scoped Turbo typecheck passes for Workshop, Docs, and Next.js.                                                                                                                                    |
+| Lint                        | Pass    | Scoped lint exits clean; remaining warnings predate the rewrite. Workshop has zero warnings.                                                                                                      |
+| Format                      | Pass    | Every changed supported file passes `oxfmt --check`; repository-wide Docs formatting still reports pre-existing drift.                                                                            |
+| Production builds           | Pass    | Docusaurus and Next.js production builds pass under Node 24.18.0.                                                                                                                                 |
+| Browser smoke               | Pass    | Desktop/mobile discovery and the disconnected API state render without uncaught errors; cached data remains readable and retry is explicit.                                                       |
+| Automated cross-surface E2E | Open P1 | Authenticated website-to-Homarr publish/install and moderator flows still need browser automation.                                                                                                |
+
+Final implementation scores (10 is best): security 9, architecture/DX 9, moderation 9, performance 9, responsive UI 9, theming 9, accessibility 8, automated testing 7. Accessibility remains below 9 until authenticated dialogs and destructive flows receive a full keyboard/screen-reader pass.
@@ -0,0 +1,23 @@
+# Workshop design system
+
+Workshop is a trustworthy community workbench inside Homarr, not a separate storefront brand.
+
+## Visual direction
+
+- Reuse the host surface: Docusaurus tokens on `homarr.dev`, Mantine components inside Homarr.
+- Use Homarr red only for primary action and focus; warnings use restrained amber and errors use red with explanatory text.
+- Keep surfaces flat, bordered, and readable. Cards may lift by 3px on pointer hover; no gradients, glass panels, or decorative dashboards.
+- Typography follows each host. Headings are compact and confident; body copy stays warm, concrete, and short.
+- Spacing follows an 8px rhythm, 12-16px corners, and 44px minimum controls.
+
+## Interaction direction
+
+- The catalog progression is discover → inspect → confirm → use.
+- Every remote state has a named loading, empty, cached, unavailable, validation, permission, and success outcome.
+- Community source is never executed on the website. Installation always follows source inspection and local validation.
+- Motion is limited to 150-200ms hover/state feedback and skeleton loading, with reduced-motion fallbacks.
+- Native dialogs or Mantine modals own focus, Escape, backdrop dismissal, and keyboard order.
+
+## Voice
+
+Clear, dependable, and community-minded. Explain what remains usable during failures and provide one direct recovery action. Avoid playful language during moderation, destructive actions, or service failures.
@@ -21,6 +21,8 @@ In Homarr, open **Management → Workshop** to browse, search, filter, inspect,

 Recently loaded listings and details are saved in the browser for up to 24 hours. If Workshop is temporarily unreachable, Homarr shows the saved catalog with a clear offline notice; browsing the rest of Homarr is unaffected. Publishing, voting, reporting, and installation remain unavailable until the connection returns.

+The public site also caches pages you have visited. If your network drops, a previously opened Workshop or documentation page can still load while the saved catalog remains on the device. Use **Check again** after connectivity returns.
+
 - Widgets are validated against `homarr-custom-widget-v2` before installation. API keys and other secrets are not included and must be configured locally.
 - CSS is loaded into the board editor for review. It is not saved until you choose **Save changes**.
 - The public website never executes submitted widget templates or CSS.
@@ -39,4 +41,4 @@ Signed-in members can vote to help useful creations rank higher. Report maliciou

 Workshop accounts use GitHub OAuth and are separate from users in a self-hosted Homarr instance. Workshop moderators can remove submissions, prevent an account from publishing, disable an account, and resolve reports. These actions require a reason and are recorded.

-The Workshop is a central service operated by Homarr at `workshop.homarr.dev`. Running the backend locally is supported for contributors developing or testing this feature, not as a private production marketplace.
+The Workshop is a central service operated by Homarr at `homarr.dev`. The documentation website and Workshop API ship in one image and use the same origin. Running it locally is supported for contributors developing or testing this feature, not as a private production marketplace.
@@ -3,10 +3,9 @@ import type { Config } from "@docusaurus/types";
 import { themes as prismThemes } from "prism-react-renderer";
 const a11yEmoji = require("@fec/remark-a11y-emoji");

-const workshopApiUrl =
-  process.env.NODE_ENV !== "production"
-    ? (process.env.WORKSHOP_API_URL ?? process.env.NEXT_PUBLIC_WORKSHOP_API_URL ?? "https://workshop.homarr.dev")
-    : "https://workshop.homarr.dev";
+// Production uses PocketBase's own origin. The explicit override exists only
+// for the standalone Docusaurus development server.
+const workshopApiUrl = process.env.WORKSHOP_API_URL ?? process.env.NEXT_PUBLIC_WORKSHOP_API_URL ?? "";

 const config: Config = {
  title: "Homarr documentation",
@@ -310,6 +309,7 @@ const config: Config = {
    ],
    "docusaurus-plugin-image-zoom",
    require.resolve("./plugins/validate-docs-coverage"),
+    require.resolve("./plugins/offline-manifest.mjs"),
    function disableExpensiveBundlerOptimizationPlugin() {
      return {
        name: "disable-expensive-bundler-optimizations",
@@ -0,0 +1,26 @@
+import { readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const collectFiles = async (directory, root = directory) => {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map((entry) => {
+      const absolutePath = path.join(directory, entry.name);
+      return entry.isDirectory() ? collectFiles(absolutePath, root) : path.relative(root, absolutePath);
+    }),
+  );
+  return files.flat();
+};
+
+export default function offlineManifestPlugin() {
+  return {
+    name: "workshop-offline-manifest",
+    async postBuild({ outDir }) {
+      const assetsDirectory = path.join(outDir, "assets");
+      const assets = (await collectFiles(assetsDirectory))
+        .filter((file) => /\.(?:css|js|woff2?)$/.test(file))
+        .map((file) => `/assets/${file.split(path.sep).join("/")}`);
+      await writeFile(path.join(outDir, "workshop-assets.json"), JSON.stringify([...assets, "/img/logo.png"]));
+    },
+  };
+}
@@ -1,16 +1,11 @@
 import React, { useEffect, useMemo, useState } from "react";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";

-import {
-  WORKSHOP_API_URL,
-  WorkshopClient,
-  type WorkshopAccountState,
-  type WorkshopRole,
-  type WorkshopUser,
-} from "@homarr/workshop";
+import { WorkshopClient, type WorkshopAccountState, type WorkshopRole, type WorkshopUser } from "@homarr/workshop";

 import { WorkshopQueryProvider } from "./WorkshopQueryProvider";
+import { WorkshopDialog, WorkshopServiceState } from "./WorkshopUi";
 import styles from "./workshop.module.css";

 type PendingAction =
@@ -29,9 +24,10 @@ export function WorkshopAdmin() {
 function WorkshopAdminContent() {
  const { siteConfig } = useDocusaurusContext();
  const client = useMemo(
-    () => new WorkshopClient((siteConfig.customFields?.workshopApiUrl as string | undefined) ?? WORKSHOP_API_URL),
+    () => new WorkshopClient((siteConfig.customFields?.workshopApiUrl as string | undefined) || window.location.origin),
    [siteConfig],
  );
+  const queryClient = useQueryClient();
  const [user, setUser] = useState<WorkshopUser | null>(null);
  const [pending, setPending] = useState<PendingAction | null>(null);
  const [error, setError] = useState("");
@@ -53,6 +49,24 @@ function WorkshopAdminContent() {
  const reports = moderationQuery.data?.reports ?? [];
  const users = moderationQuery.data?.users ?? [];
  const actions = moderationQuery.data?.actions ?? [];
+  const actionMutation = useMutation({
+    mutationKey: ["workshop", "moderation", "action"],
+    mutationFn: async ({ action, reason }: { action: PendingAction; reason: string }) => {
+      if (action.kind === "report") await client.resolveReport(action.id, action.status, reason);
+      else if (action.kind === "state") await client.updateAccountState(action.id, action.state, reason);
+      else await client.updateRole(action.id, action.role, reason);
+    },
+    onSuccess: async () => {
+      setPending(null);
+      await queryClient.invalidateQueries({ queryKey: ["workshop", "moderation"] });
+    },
+  });
+  const signInMutation = useMutation({
+    mutationKey: ["workshop", "auth", "moderator"],
+    mutationFn: () => client.signInWithGitHub(),
+    onSuccess: setUser,
+    onError: (caught) => setError(caught instanceof Error ? caught.message : "GitHub sign-in is unavailable"),
+  });

  useEffect(() => client.subscribeToAuth(setUser), [client]);
  useEffect(() => {
@@ -83,16 +97,13 @@ function WorkshopAdminContent() {
        )}
        <button
          className="button button--primary"
-          onClick={async () => {
+          disabled={signInMutation.isPending}
+          onClick={() => {
            setError("");
-            try {
-              setUser(await client.signInWithGitHub());
-            } catch (caught) {
-              setError(caught instanceof Error ? caught.message : "GitHub sign-in is unavailable");
-            }
+            signInMutation.mutate();
          }}
        >
-          Sign in with GitHub
+          {signInMutation.isPending ? "Connecting…" : "Sign in with GitHub"}
        </button>
      </main>
    );
@@ -115,10 +126,11 @@ function WorkshopAdminContent() {
        </div>
      </header>
      {(error || moderationQuery.isError) && (
-        <div className={styles.error} role="alert">
-          {error || "Moderation data is unavailable. Try again when Workshop reconnects."}{" "}
-          {moderationQuery.isError && <button onClick={() => void moderationQuery.refetch()}>Try again</button>}
-        </div>
+        <WorkshopServiceState
+          cached={Boolean(moderationQuery.data)}
+          message={error || "Moderation data is unavailable. No action can be applied until Workshop reconnects."}
+          onRetry={() => void moderationQuery.refetch()}
+        />
      )}
      <section className={styles.adminSection}>
        <h2>Open reports</h2>
@@ -258,13 +270,7 @@ function WorkshopAdminContent() {
        <ReasonDialog
          action={pending}
          onClose={() => setPending(null)}
-          onConfirm={async (reason) => {
-            if (pending.kind === "report") await client.resolveReport(pending.id, pending.status, reason);
-            else if (pending.kind === "state") await client.updateAccountState(pending.id, pending.state, reason);
-            else await client.updateRole(pending.id, pending.role, reason);
-            setPending(null);
-            await moderationQuery.refetch();
-          }}
+          onConfirm={(reason) => actionMutation.mutateAsync({ action: pending, reason })}
        />
      )}
    </main>
@@ -293,45 +299,43 @@ function ReasonDialog({
  const [error, setError] = useState("");
  const [saving, setSaving] = useState(false);
  return (
-    <div className={styles.overlay}>
-      <dialog className={styles.dialog} open aria-labelledby="moderation-reason-title">
-        <h2 id="moderation-reason-title">Confirm moderation action</h2>
-        <p>
-          This will apply <strong>{action.kind}</strong> to the selected record.
-        </p>
-        <form
-          onSubmit={async (event) => {
-            event.preventDefault();
-            setSaving(true);
-            try {
-              await onConfirm(reason);
-            } catch (caught) {
-              setError(caught instanceof Error ? caught.message : "Action failed");
-              setSaving(false);
-            }
-          }}
-        >
-          <label>
-            Reason
-            <textarea
-              required
-              minLength={3}
-              maxLength={1000}
-              value={reason}
-              onChange={(event) => setReason(event.target.value)}
-            />
-          </label>
-          {error && <p className={styles.error}>{error}</p>}
-          <div className={styles.formActions}>
-            <button type="button" className="button button--secondary" onClick={onClose}>
-              Cancel
-            </button>
-            <button disabled={saving} className="button button--danger">
-              {saving ? "Applying…" : "Apply action"}
-            </button>
-          </div>
-        </form>
-      </dialog>
-    </div>
+    <WorkshopDialog titleId="moderation-reason-title" onClose={onClose}>
+      <h2 id="moderation-reason-title">Confirm moderation action</h2>
+      <p>
+        This will apply <strong>{action.kind}</strong> to the selected record.
+      </p>
+      <form
+        onSubmit={async (event) => {
+          event.preventDefault();
+          setSaving(true);
+          try {
+            await onConfirm(reason);
+          } catch (caught) {
+            setError(caught instanceof Error ? caught.message : "Action failed");
+            setSaving(false);
+          }
+        }}
+      >
+        <label>
+          Reason
+          <textarea
+            required
+            minLength={3}
+            maxLength={1000}
+            value={reason}
+            onChange={(event) => setReason(event.target.value)}
+          />
+        </label>
+        {error && <p className={styles.error}>{error}</p>}
+        <div className={styles.formActions}>
+          <button type="button" className="button button--secondary" onClick={onClose}>
+            Cancel
+          </button>
+          <button disabled={saving} className="button button--danger">
+            {saving ? "Applying…" : "Apply action"}
+          </button>
+        </div>
+      </form>
+    </WorkshopDialog>
  );
 }
@@ -8,14 +8,16 @@ import {
  IconCopy,
  IconDownload,
  IconFlag,
+  IconHeart,
+  IconPackage,
  IconSearch,
+  IconSparkles,
  IconUpload,
 } from "@tabler/icons-react";

 import {
  MAX_CONTENT_LENGTH,
  MAX_SCREENSHOTS,
-  WORKSHOP_API_URL,
  WorkshopClient,
  type WorkshopSubmissionDetail,
  type WorkshopSubmissionInput,
@@ -27,11 +29,12 @@ import {
 import { keepPreviousData, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";

 import { WorkshopQueryProvider } from "./WorkshopQueryProvider";
+import { WorkshopDialog, WorkshopServiceState } from "./WorkshopUi";
 import styles from "./workshop.module.css";

 const useWorkshop = () => {
  const { siteConfig } = useDocusaurusContext();
-  const apiUrl = (siteConfig.customFields?.workshopApiUrl as string | undefined) ?? WORKSHOP_API_URL;
+  const apiUrl = (siteConfig.customFields?.workshopApiUrl as string | undefined) || window.location.origin;
  return useMemo(() => new WorkshopClient(apiUrl), [apiUrl]);
 };

@@ -66,6 +69,12 @@ function WorkshopAppContent() {
  const [mine, setMine] = useState(false);
  const [error, setError] = useState("");
  const [showForm, setShowForm] = useState(false);
+  const signInMutation = useMutation({
+    mutationKey: ["workshop", "auth", "sign-in"],
+    mutationFn: () => client.signInWithGitHub(),
+    onSuccess: async () => queryClient.invalidateQueries({ queryKey: ["workshop"] }),
+    onError: (caught) => setError(caught instanceof Error ? caught.message : "Sign-in failed"),
+  });

  useEffect(() => client.subscribeToAuth(setUser), [client]);
  useEffect(() => {
@@ -92,21 +101,24 @@ function WorkshopAppContent() {
  const items = listQuery.data?.items ?? [];
  const totalPages = listQuery.data?.totalPages ?? 1;

-  const signIn = async () => {
-    try {
-      await client.signInWithGitHub();
-      await queryClient.invalidateQueries({ queryKey: ["workshop"] });
-    } catch (caught) {
-      setError(caught instanceof Error ? caught.message : "Sign-in failed");
-    }
-  };
-
  return (
    <main className={styles.page}>
      <header className={styles.hero}>
        <div>
+          <span className={styles.eyebrow}>Made by the Homarr community</span>
          <h1>Workshop</h1>
-          <p>Community widgets and CSS themes, ready to inspect and use in Homarr.</p>
+          <p>Discover useful creations, inspect every line, then bring the ones you trust into Homarr.</p>
+          <ul className={styles.heroPromises} aria-label="Workshop principles">
+            <li>
+              <IconSparkles size={16} /> Community-made
+            </li>
+            <li>
+              <IconPackage size={16} /> Ready to export
+            </li>
+            <li>
+              <IconHeart size={16} /> Ranked by members
+            </li>
+          </ul>
        </div>
        <div className={styles.accountActions}>
          {user ? (
@@ -124,8 +136,12 @@ function WorkshopAppContent() {
              </button>
            </>
          ) : (
-            <button className="button button--primary" onClick={() => void signIn()}>
-              <IconBrandGithub size={18} /> Sign in with GitHub
+            <button
+              className="button button--primary"
+              disabled={signInMutation.isPending}
+              onClick={() => signInMutation.mutate()}
+            >
+              <IconBrandGithub size={18} /> {signInMutation.isPending ? "Connecting…" : "Sign in with GitHub"}
            </button>
          )}
        </div>
@@ -194,14 +210,11 @@ function WorkshopAppContent() {
      </div>

      {(error || listQuery.isError || listQuery.fetchStatus === "paused") && (
-        <div className={styles.error} role="alert">
-          <strong>{items.length ? "Showing saved Workshop results." : "Workshop is unavailable."}</strong>{" "}
-          {error ||
-            (items.length
-              ? "Some details and actions may be unavailable until the service reconnects."
-              : "Homarr and the documentation remain available while the community service is offline.")}{" "}
-          <button onClick={() => void listQuery.refetch()}>Try again</button>
-        </div>
+        <WorkshopServiceState
+          cached={items.length > 0}
+          message={error || undefined}
+          onRetry={() => void listQuery.refetch()}
+        />
      )}
      {listQuery.isPending ? (
        <WorkshopSkeleton />
@@ -213,8 +226,20 @@ function WorkshopAppContent() {
        </div>
      ) : listQuery.isError || listQuery.fetchStatus === "paused" ? null : (
        <section className={styles.empty}>
+          <IconSearch size={32} aria-hidden />
          <h2>No creations found</h2>
-          <p>Adjust the filters, or share the first creation in this category.</p>
+          <p>Try a broader search or clear the filters to explore everything the community has shared.</p>
+          <button
+            className="button button--secondary button--sm"
+            onClick={() => {
+              setSearch("");
+              setType("all");
+              setSort("top");
+              setPage(1);
+            }}
+          >
+            Clear filters
+          </button>
        </section>
      )}

@@ -265,7 +290,9 @@ function WorkshopCard({ client, item }: { client: WorkshopClient; item: Workshop
          </span>
        </div>
        <h2>
-          <Link to={`/workshop/${item.id}`}>{item.title}</Link>
+          <Link className={styles.cardLink} to={`/workshop/${item.id}`}>
+            {item.title}
+          </Link>
        </h2>
        <p>{item.description || "No description provided."}</p>
        <small>
@@ -463,51 +490,49 @@ function ModerationRemovalForm({
  onRemoved: () => void;
 }) {
  const [reason, setReason] = useState("");
-  const [error, setError] = useState("");
-  const [pending, setPending] = useState(false);
+  const removeMutation = useMutation({
+    mutationKey: ["workshop", "moderation", "remove", submission.id],
+    mutationFn: () => client.removeSubmission(submission.id, reason),
+    onSuccess: onRemoved,
+  });
  return (
-    <div className={styles.overlay}>
-      <dialog className={styles.dialog} open aria-labelledby="remove-submission-title">
-        <h2 id="remove-submission-title">Remove {submission.title}</h2>
-        <p>
-          This permanently deletes the submission, files, votes, and reports. A metadata snapshot is retained in
-          moderation history.
-        </p>
-        <form
-          onSubmit={async (event) => {
-            event.preventDefault();
-            setPending(true);
-            try {
-              await client.removeSubmission(submission.id, reason);
-              onRemoved();
-            } catch (caught) {
-              setError(caught instanceof Error ? caught.message : "Removal failed");
-              setPending(false);
-            }
-          }}
-        >
-          <label>
-            Reason
-            <textarea
-              required
-              minLength={3}
-              maxLength={1000}
-              value={reason}
-              onChange={(event) => setReason(event.target.value)}
-            />
-          </label>
-          {error && <p className={styles.error}>{error}</p>}
-          <div className={styles.formActions}>
-            <button type="button" className="button button--secondary" onClick={onClose}>
-              Cancel
-            </button>
-            <button disabled={pending} className="button button--danger">
-              {pending ? "Removing…" : "Remove permanently"}
-            </button>
-          </div>
-        </form>
-      </dialog>
-    </div>
+    <WorkshopDialog titleId="remove-submission-title" onClose={onClose}>
+      <h2 id="remove-submission-title">Remove {submission.title}</h2>
+      <p>
+        This permanently deletes the submission, files, votes, and reports. A metadata snapshot is retained in
+        moderation history.
+      </p>
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          removeMutation.mutate();
+        }}
+      >
+        <label>
+          Reason
+          <textarea
+            required
+            minLength={3}
+            maxLength={1000}
+            value={reason}
+            onChange={(event) => setReason(event.target.value)}
+          />
+        </label>
+        {removeMutation.error && (
+          <p className={styles.error} role="alert">
+            {removeMutation.error instanceof Error ? removeMutation.error.message : "Removal failed"}
+          </p>
+        )}
+        <div className={styles.formActions}>
+          <button type="button" className="button button--secondary" onClick={onClose}>
+            Cancel
+          </button>
+          <button disabled={removeMutation.isPending} className="button button--danger">
+            {removeMutation.isPending ? "Removing…" : "Remove permanently"}
+          </button>
+        </div>
+      </form>
+    </WorkshopDialog>
  );
 }

@@ -529,125 +554,112 @@ function SubmissionForm({
  const [changelog, setChangelog] = useState(existing?.changelog ?? "");
  const [screenshots, setScreenshots] = useState<File[]>([]);
  const [removedScreenshots, setRemovedScreenshots] = useState<string[]>([]);
-  const [error, setError] = useState("");
-  const [pending, setPending] = useState(false);
  const retainedScreenshotCount = (existing?.screenshots.length ?? 0) - removedScreenshots.length;
  const remainingScreenshotSlots = Math.max(0, MAX_SCREENSHOTS - retainedScreenshotCount);
  useEffect(() => {
    setScreenshots((current) => current.slice(0, remainingScreenshotSlots));
  }, [remainingScreenshotSlots]);
-  const submit = async (event: React.FormEvent) => {
-    event.preventDefault();
-    setPending(true);
-    setError("");
-    const input: WorkshopSubmissionInput = { type, title, description, content, changelog };
-    try {
+  const saveMutation = useMutation({
+    mutationKey: ["workshop", existing ? "update" : "create", existing?.id],
+    mutationFn: async (input: WorkshopSubmissionInput) => {
      if (!client.currentUser) await client.signInWithGitHub();
      if (existing) {
-        await client.update(existing.id, input, screenshots, removedScreenshots);
-      } else {
-        await client.create(input, screenshots);
+        return client.update(existing.id, input, screenshots, removedScreenshots);
      }
-      await onSaved();
-    } catch (caught) {
-      setError(caught instanceof Error ? caught.message : "Could not save submission");
-    } finally {
-      setPending(false);
-    }
-  };
+      return client.create(input, screenshots);
+    },
+    onSuccess: onSaved,
+  });
  return (
-    <div
-      className={styles.overlay}
-      role="presentation"
-      onMouseDown={(event) => {
-        if (event.target === event.currentTarget) onClose();
-      }}
-    >
-      <dialog className={styles.dialog} open aria-labelledby="submission-form-title">
-        <h2 id="submission-form-title">{existing ? "Update creation" : "Share with the community"}</h2>
-        <form onSubmit={(event) => void submit(event)}>
-          <label>
-            Type
-            <select
-              disabled={Boolean(existing)}
-              value={type}
-              onChange={(event) => setType(event.target.value as WorkshopSubmissionType)}
-            >
-              <option value="widget">Custom widget</option>
-              <option value="css">CSS theme</option>
-            </select>
-          </label>
-          <label>
-            Title
+    <WorkshopDialog titleId="submission-form-title" onClose={onClose}>
+      <h2 id="submission-form-title">{existing ? "Update creation" : "Share with the community"}</h2>
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          saveMutation.mutate({ type, title, description, content, changelog });
+        }}
+      >
+        <label>
+          Type
+          <select
+            disabled={Boolean(existing)}
+            value={type}
+            onChange={(event) => setType(event.target.value as WorkshopSubmissionType)}
+          >
+            <option value="widget">Custom widget</option>
+            <option value="css">CSS theme</option>
+          </select>
+        </label>
+        <label>
+          Title
+          <input
+            required
+            minLength={3}
+            maxLength={100}
+            value={title}
+            onChange={(event) => setTitle(event.target.value)}
+          />
+        </label>
+        <label>
+          Description
+          <textarea maxLength={2000} value={description} onChange={(event) => setDescription(event.target.value)} />
+        </label>
+        <label>
+          {type === "widget" ? "Widget JSON" : "CSS source"}
+          <textarea
+            className={styles.editor}
+            required
+            maxLength={MAX_CONTENT_LENGTH}
+            value={content}
+            onChange={(event) => setContent(event.target.value)}
+          />
+        </label>
+        <label>
+          Changelog
+          <textarea maxLength={2000} value={changelog} onChange={(event) => setChangelog(event.target.value)} />
+        </label>
+        <label>
+          Screenshots (PNG, JPG, or WebP, {remainingScreenshotSlots} available)
+          <input
+            type="file"
+            accept="image/png,image/jpeg,image/webp"
+            multiple
+            onChange={(event) =>
+              setScreenshots(Array.from(event.target.files ?? []).slice(0, remainingScreenshotSlots))
+            }
+          />
+        </label>
+        {existing?.screenshots.map((screenshot) => (
+          <label className={styles.checkbox} key={screenshot}>
            <input
-              required
-              minLength={3}
-              maxLength={100}
-              value={title}
-              onChange={(event) => setTitle(event.target.value)}
-            />
-          </label>
-          <label>
-            Description
-            <textarea maxLength={2000} value={description} onChange={(event) => setDescription(event.target.value)} />
-          </label>
-          <label>
-            {type === "widget" ? "Widget JSON" : "CSS source"}
-            <textarea
-              className={styles.editor}
-              required
-              maxLength={MAX_CONTENT_LENGTH}
-              value={content}
-              onChange={(event) => setContent(event.target.value)}
-            />
-          </label>
-          <label>
-            Changelog
-            <textarea maxLength={2000} value={changelog} onChange={(event) => setChangelog(event.target.value)} />
-          </label>
-          <label>
-            Screenshots (PNG, JPG, or WebP, {remainingScreenshotSlots} available)
-            <input
-              type="file"
-              accept="image/png,image/jpeg,image/webp"
-              multiple
+              type="checkbox"
+              checked={removedScreenshots.includes(screenshot)}
              onChange={(event) =>
-                setScreenshots(Array.from(event.target.files ?? []).slice(0, remainingScreenshotSlots))
+                setRemovedScreenshots((current) =>
+                  event.target.checked
+                    ? [...current, screenshot]
+                    : current.filter((filename) => filename !== screenshot),
+                )
              }
            />
+            Remove existing screenshot {screenshot}
          </label>
-          {existing?.screenshots.map((screenshot) => (
-            <label className={styles.checkbox} key={screenshot}>
-              <input
-                type="checkbox"
-                checked={removedScreenshots.includes(screenshot)}
-                onChange={(event) =>
-                  setRemovedScreenshots((current) =>
-                    event.target.checked
-                      ? [...current, screenshot]
-                      : current.filter((filename) => filename !== screenshot),
-                  )
-                }
-              />
-              Remove existing screenshot {screenshot}
-            </label>
-          ))}
-          {error && (
-            <p className={styles.error} role="alert">
-              {error}
-            </p>
-          )}
-          <div className={styles.formActions}>
-            <button type="button" className="button button--secondary" onClick={onClose}>
-              Cancel
-            </button>
-            <button disabled={pending} className="button button--primary">
-              {pending ? "Saving…" : existing ? "Save update" : "Publish creation"}
-            </button>
-          </div>
-        </form>
-      </dialog>
-    </div>
+        ))}
+        {saveMutation.error && (
+          <p className={styles.error} role="alert">
+            {saveMutation.error instanceof Error ? saveMutation.error.message : "Could not save submission"}
+          </p>
+        )}
+        <div className={styles.formActions}>
+          <button type="button" className="button button--secondary" onClick={onClose}>
+            Cancel
+          </button>
+          <button disabled={saveMutation.isPending} className="button button--primary">
+            {saveMutation.isPending ? "Saving…" : existing ? "Save update" : "Publish creation"}
+          </button>
+        </div>
+      </form>
+    </WorkshopDialog>
  );
 }

@@ -662,53 +674,58 @@ function ReportForm({
 }) {
  const [category, setCategory] = useState<"malicious" | "spam" | "copyright" | "inappropriate" | "other">("malicious");
  const [explanation, setExplanation] = useState("");
-  const [error, setError] = useState("");
+  const reportMutation = useMutation({
+    mutationKey: ["workshop", "report", submissionId],
+    mutationFn: async () => {
+      if (!client.currentUser) await client.signInWithGitHub();
+      return client.report(submissionId, category, explanation);
+    },
+    onSuccess: onClose,
+  });
  return (
-    <div className={styles.overlay}>
-      <dialog className={styles.dialog} open aria-labelledby="report-title">
-        <h2 id="report-title">Report submission</h2>
-        <form
-          onSubmit={async (event) => {
-            event.preventDefault();
-            try {
-              if (!client.currentUser) await client.signInWithGitHub();
-              await client.report(submissionId, category, explanation);
-              onClose();
-            } catch (caught) {
-              setError(caught instanceof Error ? caught.message : "Could not send report");
-            }
-          }}
-        >
-          <label>
-            Reason
-            <select value={category} onChange={(event) => setCategory(event.target.value as typeof category)}>
-              <option value="malicious">Malicious</option>
-              <option value="spam">Spam</option>
-              <option value="copyright">Copyright</option>
-              <option value="inappropriate">Inappropriate</option>
-              <option value="other">Other</option>
-            </select>
-          </label>
-          <label>
-            Details
-            <textarea
-              required
-              minLength={3}
-              maxLength={1000}
-              value={explanation}
-              onChange={(event) => setExplanation(event.target.value)}
-            />
-          </label>
-          {error && <p className={styles.error}>{error}</p>}
-          <div className={styles.formActions}>
-            <button type="button" className="button button--secondary" onClick={onClose}>
-              Cancel
-            </button>
-            <button className="button button--primary">Submit report</button>
-          </div>
-        </form>
-      </dialog>
-    </div>
+    <WorkshopDialog titleId="report-title" onClose={onClose}>
+      <h2 id="report-title">Report submission</h2>
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          reportMutation.mutate();
+        }}
+      >
+        <label>
+          Reason
+          <select value={category} onChange={(event) => setCategory(event.target.value as typeof category)}>
+            <option value="malicious">Malicious</option>
+            <option value="spam">Spam</option>
+            <option value="copyright">Copyright</option>
+            <option value="inappropriate">Inappropriate</option>
+            <option value="other">Other</option>
+          </select>
+        </label>
+        <label>
+          Details
+          <textarea
+            required
+            minLength={3}
+            maxLength={1000}
+            value={explanation}
+            onChange={(event) => setExplanation(event.target.value)}
+          />
+        </label>
+        {reportMutation.error && (
+          <p className={styles.error} role="alert">
+            {reportMutation.error instanceof Error ? reportMutation.error.message : "Could not send report"}
+          </p>
+        )}
+        <div className={styles.formActions}>
+          <button type="button" className="button button--secondary" onClick={onClose}>
+            Cancel
+          </button>
+          <button disabled={reportMutation.isPending} className="button button--primary">
+            {reportMutation.isPending ? "Sending…" : "Submit report"}
+          </button>
+        </div>
+      </form>
+    </WorkshopDialog>
  );
 }

@@ -0,0 +1,69 @@
+import React, { type PropsWithChildren, useEffect, useRef } from "react";
+import Link from "@docusaurus/Link";
+import { IconBooks, IconCloudOff, IconRefresh } from "@tabler/icons-react";
+
+import styles from "./workshop.module.css";
+
+export function WorkshopServiceState({
+  cached,
+  message,
+  onRetry,
+}: {
+  cached: boolean;
+  message?: string;
+  onRetry: () => void;
+}) {
+  return (
+    <section className={styles.serviceState} aria-live="polite">
+      <span className={styles.serviceStateIcon} aria-hidden>
+        <IconCloudOff size={24} />
+      </span>
+      <div>
+        <h2>{cached ? "Browsing saved creations" : "Workshop is taking a break"}</h2>
+        <p>
+          {message ??
+            (cached
+              ? "The catalog saved on this device is still available. Live details and community actions will return when the service reconnects."
+              : "Community creations cannot be reached right now. Homarr and its documentation remain fully available.")}
+        </p>
+        <div className={styles.serviceStateActions}>
+          <button className="button button--primary button--sm" onClick={onRetry}>
+            <IconRefresh size={16} /> Check again
+          </button>
+          <Link className="button button--secondary button--sm" to="/docs/management/workshop">
+            <IconBooks size={16} /> Read the guide
+          </Link>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export function WorkshopDialog({
+  titleId,
+  onClose,
+  children,
+}: PropsWithChildren<{ titleId: string; onClose: () => void }>) {
+  const ref = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    const dialog = ref.current;
+    if (!dialog) return;
+    dialog.showModal();
+    return () => dialog.close();
+  }, []);
+
+  return (
+    <dialog
+      ref={ref}
+      className={styles.dialog}
+      aria-labelledby={titleId}
+      onCancel={(event) => {
+        event.preventDefault();
+        onClose();
+      }}
+    >
+      <div className={styles.dialogSurface}>{children}</div>
+    </dialog>
+  );
+}
@@ -1,164 +1,343 @@
 .page {
-  max-width: 1240px;
+  --workshop-ease: cubic-bezier(0.25, 1, 0.5, 1);
+  max-width: 1180px;
  min-height: 70vh;
  margin: 0 auto;
-  padding: 2.5rem 1.25rem 5rem;
+  padding: clamp(2rem, 5vw, 4.5rem) 1.25rem 5rem;
 }
+
 .hero {
-  display: flex;
-  align-items: flex-end;
-  justify-content: space-between;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
  gap: 2rem;
-  margin-bottom: 1.5rem;
+  margin-bottom: 2rem;
 }
+
+.eyebrow {
+  display: block;
+  margin-bottom: 0.45rem;
+  color: var(--ifm-color-primary);
+  font-size: 0.76rem;
+  font-weight: 750;
+  letter-spacing: 0.09em;
+  text-transform: uppercase;
+}
+
 .hero h1,
 .detail h1 {
  margin: 0;
-  font-size: 2.25rem;
-  letter-spacing: -0.025em;
+  font-size: clamp(2.35rem, 6vw, 4.25rem);
+  line-height: 0.98;
+  letter-spacing: -0.045em;
 }
+
 .hero p {
-  max-width: 65ch;
-  margin: 0.5rem 0 0;
+  max-width: 62ch;
+  margin: 0.85rem 0 0;
  color: var(--ifm-color-emphasis-700);
+  font-size: clamp(1rem, 2vw, 1.12rem);
+  line-height: 1.65;
 }
+
+.heroPromises {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.55rem 1rem;
+  padding: 0;
+  margin: 1.1rem 0 0;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.82rem;
+  list-style: none;
+}
+
+.heroPromises li,
 .accountActions,
 .detailActions,
-.formActions {
+.formActions,
+.serviceStateActions {
  display: flex;
  align-items: center;
-  flex-wrap: wrap;
-  gap: 0.75rem;
 }
+
+.heroPromises li {
+  gap: 0.35rem;
+}
+
+.accountActions,
+.detailActions,
+.formActions,
+.serviceStateActions {
+  flex-wrap: wrap;
+  gap: 0.7rem;
+}
+
 .accountActions :global(.button),
-.detailActions :global(.button) {
+.detailActions :global(.button),
+.serviceStateActions :global(.button) {
  display: inline-flex;
  align-items: center;
+  justify-content: center;
  gap: 0.4rem;
 }
+
 .safety {
  display: flex;
  align-items: flex-start;
  gap: 0.75rem;
-  padding: 0.85rem 1rem;
-  margin-bottom: 1.5rem;
-  border: 1px solid var(--ifm-color-warning-dark);
-  border-radius: 10px;
-  background: color-mix(in srgb, var(--ifm-color-warning) 10%, transparent);
+  padding: 0.9rem 1rem;
+  margin-bottom: 1rem;
+  border: 1px solid color-mix(in srgb, var(--ifm-color-warning) 55%, var(--ifm-color-emphasis-300));
+  border-radius: 12px;
+  background: color-mix(in srgb, var(--ifm-color-warning) 8%, var(--ifm-background-surface-color));
 }
+
+.safety svg {
+  flex: none;
+  margin-top: 0.1rem;
+}
+
 .safety p {
  margin: 0;
+  color: var(--ifm-color-emphasis-800);
+  font-size: 0.9rem;
 }
+
 .toolbar {
-  display: flex;
+  display: grid;
+  grid-template-columns: minmax(260px, 1fr) 150px 150px auto;
  align-items: end;
-  flex-wrap: wrap;
  gap: 0.75rem;
-  padding: 0.75rem;
-  margin-bottom: 1.5rem;
+  padding: 0.85rem;
+  margin-bottom: 1.25rem;
  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: 10px;
+  border-radius: 14px;
+  background: var(--ifm-background-surface-color);
+  box-shadow: 0 8px 28px rgb(0 0 0 / 0.04);
 }
+
 .toolbar label,
 .dialog label {
  display: grid;
-  gap: 0.3rem;
-  font-size: 0.8rem;
-  font-weight: 600;
+  gap: 0.35rem;
+  font-size: 0.78rem;
+  font-weight: 700;
 }
+
 .toolbar input,
 .toolbar select,
 .dialog input,
 .dialog select,
 .dialog textarea {
+  width: 100%;
  min-height: 44px;
-  padding: 0.55rem 0.7rem;
+  padding: 0.6rem 0.72rem;
  border: 1px solid var(--ifm-color-emphasis-400);
-  border-radius: 7px;
+  border-radius: 9px;
  color: var(--ifm-font-color-base);
-  background: var(--ifm-background-surface-color);
+  background: var(--ifm-background-color);
  font: inherit;
+  transition:
+    border-color 150ms ease,
+    box-shadow 150ms ease;
 }
+
+.toolbar input:focus-visible,
+.toolbar select:focus-visible,
+.dialog input:focus-visible,
+.dialog select:focus-visible,
+.dialog textarea:focus-visible,
+.pagination button:focus-visible,
+.rowActions button:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 2px;
+}
+
 .search {
  position: relative;
-  flex: 1 1 280px;
 }
+
 .search svg {
  position: absolute;
-  left: 0.75rem;
-  bottom: 0.8rem;
+  z-index: 1;
+  left: 0.8rem;
+  bottom: 0.82rem;
  color: var(--ifm-color-emphasis-600);
+  pointer-events: none;
 }
+
 .search input {
-  width: 100%;
-  padding-left: 2.25rem;
+  padding-left: 2.35rem;
 }
+
 .checkbox {
  display: flex !important;
  grid-auto-flow: column;
  align-items: center;
  min-height: 44px;
 }
+
 .checkbox input {
+  width: auto;
  min-height: auto;
 }
+
+.serviceState {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  gap: 1rem;
+  padding: clamp(1.1rem, 3vw, 1.5rem);
+  margin: 1.25rem 0;
+  border: 1px solid color-mix(in srgb, var(--ifm-color-warning) 45%, var(--ifm-color-emphasis-300));
+  border-radius: 14px;
+  background: color-mix(in srgb, var(--ifm-color-warning) 7%, var(--ifm-background-surface-color));
+}
+
+.serviceStateIcon {
+  display: grid;
+  width: 44px;
+  height: 44px;
+  place-items: center;
+  border-radius: 10px;
+  color: var(--ifm-color-warning-darkest);
+  background: color-mix(in srgb, var(--ifm-color-warning) 18%, transparent);
+}
+
+.serviceState h2 {
+  margin: 0 0 0.25rem;
+  font-size: 1.05rem;
+}
+
+.serviceState p {
+  max-width: 70ch;
+  margin: 0 0 0.85rem;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.9rem;
+}
+
 .grid {
  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(270px, 1fr));
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, 270px), 1fr));
  gap: 1rem;
 }
+
 .card {
+  position: relative;
  overflow: hidden;
  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: 12px;
+  border-radius: 14px;
  background: var(--ifm-background-surface-color);
+  box-shadow: 0 4px 14px rgb(0 0 0 / 0.035);
+  transition:
+    transform 200ms var(--workshop-ease),
+    border-color 200ms ease,
+    box-shadow 200ms var(--workshop-ease);
 }
+
+.card:hover,
+.card:focus-within {
+  border-color: color-mix(in srgb, var(--ifm-color-primary) 55%, var(--ifm-color-emphasis-300));
+  box-shadow: 0 14px 34px rgb(0 0 0 / 0.1);
+  transform: translateY(-3px);
+}
+
 .card img,
 .cardPlaceholder {
  width: 100%;
  aspect-ratio: 3 / 2;
  object-fit: cover;
 }
+
 .cardPlaceholder {
  display: grid;
  place-items: center;
-  background: var(--ifm-color-emphasis-100);
  color: var(--ifm-color-emphasis-600);
-  font: 700 1.5rem var(--ifm-font-family-monospace);
+  background: color-mix(in srgb, var(--ifm-color-primary) 6%, var(--ifm-color-emphasis-100));
+  font: 750 1.45rem var(--ifm-font-family-monospace);
 }
+
 .cardBody {
  padding: 1rem;
 }
+
 .cardBody h2 {
-  margin: 0.4rem 0;
+  margin: 0.45rem 0;
  font-size: 1.08rem;
 }
+
+.cardLink::after {
+  position: absolute;
+  content: "";
+  inset: 0;
+}
+
+.cardLink:focus-visible {
+  outline: none;
+}
+
+.card:has(.cardLink:focus-visible) {
+  outline: 3px solid var(--ifm-color-primary);
+  outline-offset: 3px;
+}
+
 .cardBody p {
  min-height: 2.7em;
-  margin: 0 0 0.65rem;
+  margin: 0 0 0.7rem;
  color: var(--ifm-color-emphasis-700);
-  font-size: 0.9rem;
+  font-size: 0.88rem;
 }
+
+.cardBody small {
+  color: var(--ifm-color-emphasis-600);
+}
+
 .cardMeta {
  display: flex;
  justify-content: space-between;
  color: var(--ifm-color-emphasis-700);
-  font-size: 0.75rem;
-  font-weight: 700;
+  font-size: 0.72rem;
+  font-weight: 750;
+  letter-spacing: 0.035em;
+  text-transform: uppercase;
 }
+
 .error {
  padding: 0.85rem 1rem;
  margin: 1rem 0;
-  border-radius: 8px;
+  border: 1px solid color-mix(in srgb, var(--ifm-color-danger) 45%, transparent);
+  border-radius: 10px;
  color: var(--ifm-color-danger-contrast-foreground);
  background: var(--ifm-color-danger-contrast-background);
 }
+
 .empty {
-  padding: 4rem 1rem;
+  display: grid;
+  max-width: 620px;
+  min-height: 310px;
+  place-items: center;
+  align-content: center;
+  gap: 0.45rem;
+  padding: 3rem 1.25rem;
+  margin: 0 auto;
  text-align: center;
  border: 1px dashed var(--ifm-color-emphasis-400);
-  border-radius: 12px;
+  border-radius: 16px;
+  color: var(--ifm-color-emphasis-700);
 }
+
+.empty h2,
+.empty p {
+  margin: 0;
+}
+
+.empty svg {
+  color: var(--ifm-color-primary);
+}
+
+.empty :global(.button) {
+  margin-top: 0.75rem;
+}
+
 .pagination {
  display: flex;
  justify-content: center;
@@ -166,134 +345,248 @@
  gap: 1rem;
  margin-top: 2rem;
 }
+
 .pagination button {
  min-height: 44px;
-  padding: 0.5rem 0.8rem;
+  padding: 0.5rem 0.85rem;
 }
+
 .skeleton {
  min-height: 310px;
-  border-radius: 12px;
+  border-radius: 14px;
  background: var(--ifm-color-emphasis-200);
  animation: pulse 1.5s ease-in-out infinite;
 }
+
 .detail {
-  margin-top: 1.5rem;
+  margin-top: 1.75rem;
 }
+
 .detail header {
  max-width: 75ch;
 }
+
+.detail h1 {
+  margin-top: 0.5rem;
+  font-size: clamp(2.1rem, 5vw, 3.6rem);
+}
+
 .type {
  display: inline-block;
-  margin-bottom: 0.5rem;
  color: var(--ifm-color-primary);
-  font-weight: 700;
+  font-size: 0.78rem;
+  font-weight: 750;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
 }
+
 .gallery {
  display: flex;
  gap: 1rem;
  overflow-x: auto;
+  padding-bottom: 0.6rem;
  margin: 1.5rem 0;
  scroll-snap-type: x mandatory;
 }
+
 .gallery img {
  width: min(720px, 85vw);
  max-height: 480px;
  object-fit: contain;
-  border-radius: 10px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 12px;
  background: var(--ifm-color-emphasis-100);
  scroll-snap-align: start;
 }
+
 .detailActions {
  margin: 1.5rem 0 2rem;
 }
+
 .sourceHint {
  color: var(--ifm-color-emphasis-700);
 }
+
 .source {
  max-height: 560px;
  overflow: auto;
  padding: 1rem;
-  border-radius: 8px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 10px;
  font-size: 0.78rem;
 }
-.overlay {
-  position: fixed;
-  z-index: 500;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  padding: 1rem;
-  background: rgb(0 0 0 / 0.7);
-}
+
 .dialog {
-  width: min(680px, 100%);
-  max-height: 90vh;
+  width: min(700px, calc(100vw - 2rem));
+  max-height: min(90vh, 900px);
+  padding: 0;
+  overflow: visible;
+  border: 0;
+  border-radius: 16px;
+  color: var(--ifm-font-color-base);
+  background: transparent;
+  box-shadow: 0 24px 80px rgb(0 0 0 / 0.35);
+}
+
+.dialog::backdrop {
+  background: rgb(0 0 0 / 0.68);
+  backdrop-filter: blur(3px);
+}
+
+.dialogSurface {
+  max-height: min(90vh, 900px);
  overflow-y: auto;
-  padding: 1.25rem;
-  border-radius: 12px;
+  padding: clamp(1.15rem, 4vw, 1.6rem);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 16px;
  background: var(--ifm-background-color);
 }
+
+.dialogSurface > h2 {
+  margin-top: 0;
+}
+
 .dialog form {
  display: grid;
  gap: 1rem;
 }
+
 .dialog textarea {
-  min-height: 88px;
+  min-height: 96px;
  resize: vertical;
 }
+
 .dialog .editor {
  min-height: 240px;
  font-family: var(--ifm-font-family-monospace);
  font-size: 0.78rem;
 }
+
 .formActions {
  justify-content: flex-end;
 }
-@keyframes pulse {
-  50% {
-    opacity: 0.55;
-  }
-}
-@media (max-width: 700px) {
-  .hero {
-    align-items: stretch;
-    flex-direction: column;
-  }
-  .accountActions > * {
-    flex: 1;
-    justify-content: center;
-  }
-  .toolbar > label {
-    flex: 1 1 100%;
-  }
-}
-@media (prefers-reduced-motion: reduce) {
-  .skeleton {
-    animation: none;
-  }
-}
+
 .adminSection {
  margin: 2rem 0;
 }
+
 .tableWrap {
  overflow-x: auto;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 12px;
 }
+
 .tableWrap table {
  width: 100%;
+  margin: 0;
  border-collapse: collapse;
 }
+
 .tableWrap th,
 .tableWrap td {
-  padding: 0.7rem;
+  padding: 0.75rem;
+  border: 0;
  border-bottom: 1px solid var(--ifm-color-emphasis-300);
  text-align: left;
  vertical-align: top;
 }
+
+.tableWrap tr:last-child td {
+  border-bottom: 0;
+}
+
 .rowActions {
  display: flex;
  flex-wrap: wrap;
  gap: 0.4rem;
 }
+
 .rowActions button {
  min-height: 36px;
 }
+
+@keyframes pulse {
+  50% {
+    opacity: 0.55;
+  }
+}
+
+@media (max-width: 820px) {
+  .hero {
+    grid-template-columns: 1fr;
+    gap: 1.4rem;
+  }
+
+  .accountActions > * {
+    flex: 1 1 auto;
+  }
+
+  .toolbar {
+    grid-template-columns: 1fr 1fr;
+  }
+
+  .search {
+    grid-column: 1 / -1;
+  }
+}
+
+@media (max-width: 520px) {
+  .page {
+    padding-inline: 1rem;
+  }
+
+  .hero h1 {
+    font-size: 2.75rem;
+  }
+
+  .heroPromises {
+    display: grid;
+  }
+
+  .accountActions,
+  .detailActions,
+  .formActions,
+  .serviceStateActions {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .accountActions > *,
+  .detailActions > *,
+  .formActions > *,
+  .serviceStateActions > * {
+    width: 100%;
+  }
+
+  .toolbar {
+    grid-template-columns: 1fr;
+  }
+
+  .search {
+    grid-column: auto;
+  }
+
+  .serviceState {
+    grid-template-columns: 1fr;
+  }
+
+  .pagination {
+    justify-content: space-between;
+    gap: 0.5rem;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton {
+    animation: none;
+  }
+
+  .card {
+    transition: none;
+  }
+
+  .card:hover,
+  .card:focus-within {
+    transform: none;
+  }
+}
@@ -0,0 +1,11 @@
+import React, { type PropsWithChildren, useEffect } from "react";
+
+export default function Root({ children }: PropsWithChildren) {
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production" && "serviceWorker" in navigator) {
+      void navigator.serviceWorker.register("/workshop-sw.js", { scope: "/" });
+    }
+  }, []);
+
+  return children;
+}
@@ -0,0 +1,46 @@
+const CACHE_NAME = "homarr-site-v2";
+const SHELL_PATHS = ["/", "/workshop/", "/docs/management/workshop/", "/img/logo.png"];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then(async (cache) => {
+      const manifest = await fetch("/workshop-assets.json")
+        .then((response) => response.json())
+        .catch(() => []);
+      await Promise.allSettled([...SHELL_PATHS, ...manifest].map((path) => cache.add(path)));
+    }),
+  );
+  self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))))
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  const request = event.request;
+  const url = new URL(request.url);
+  if (request.method !== "GET" || url.origin !== self.location.origin || url.pathname.startsWith("/api/")) return;
+
+  event.respondWith(
+    fetch(request)
+      .then((response) => {
+        if (response.ok) {
+          const copy = response.clone();
+          event.waitUntil(caches.open(CACHE_NAME).then((cache) => cache.put(request, copy)));
+        }
+        return response;
+      })
+      .catch(async () => {
+        const cached = await caches.match(request);
+        if (cached) return cached;
+        if (request.mode === "navigate") return (await caches.match("/workshop/")) ?? Response.error();
+        return Response.error();
+      }),
+  );
+});
@@ -12,6 +12,7 @@ import {
  Group,
  Image,
  Modal,
+  Paper,
  Pagination,
  Select,
  SimpleGrid,
@@ -25,6 +26,7 @@ import { useDebouncedValue, useDisclosure } from "@mantine/hooks";
 import {
  IconAlertTriangle,
  IconBrandGithub,
+  IconBuildingStore,
  IconDownload,
  IconExternalLink,
  IconSearch,
@@ -113,10 +115,34 @@ function WorkshopBrowserContent({ initialType = "all", lockedType, onUse, useLab

  return (
    <Stack gap="lg">
+      <Paper withBorder p="lg" radius="md">
+        <Group justify="space-between" align="flex-start" wrap="wrap">
+          <Group align="flex-start" wrap="nowrap">
+            <Box
+              p="sm"
+              bg="var(--mantine-color-default-hover)"
+              style={{ borderRadius: "var(--mantine-radius-md)", lineHeight: 0 }}
+            >
+              <IconBuildingStore size={24} aria-hidden />
+            </Box>
+            <Box>
+              <Text fw={700} size="lg">
+                {t("intro.title")}
+              </Text>
+              <Text c="dimmed" size="sm" maw={620}>
+                {t("intro.description")}
+              </Text>
+            </Box>
+          </Group>
+          <Badge color={online ? "green" : "yellow"} variant="light">
+            {online ? t("status.connected") : t("status.offline")}
+          </Badge>
+        </Group>
+      </Paper>
      <Alert icon={<IconAlertTriangle size={18} />} color="yellow" title={t("safety.title")}>
        {t("safety.description")}
      </Alert>
-      <Group align="end">
+      <SimpleGrid cols={{ base: 1, sm: lockedType ? 2 : 3 }} spacing="sm">
        <TextInput
          label={t("search.label")}
          placeholder={t("search.placeholder")}
@@ -126,7 +152,6 @@ function WorkshopBrowserContent({ initialType = "all", lockedType, onUse, useLab
            setSearch(event.currentTarget.value);
            setPage(1);
          }}
-          style={{ flex: 1 }}
        />
        <Select
          label={t("filter.type")}
@@ -154,7 +179,7 @@ function WorkshopBrowserContent({ initialType = "all", lockedType, onUse, useLab
            { value: "newest", label: t("filter.newest") },
          ]}
        />
-      </Group>
+      </SimpleGrid>
      {(query.isError || query.fetchStatus === "paused") && (
        <Alert
          icon={<IconWifiOff size={18} />}
@@ -169,11 +194,17 @@ function WorkshopBrowserContent({ initialType = "all", lockedType, onUse, useLab
                  ? t("offline.unavailableDescription")
                  : t("offline.description")}
            </Text>
-            <Group>
+            <Group wrap="wrap">
              <Button size="xs" variant="light" onClick={() => void query.refetch()}>
                {t("action.retry")}
              </Button>
-              <Button size="xs" variant="subtle" component="a" href={WORKSHOP_WEB_URL} target="_blank">
+              <Button
+                size="xs"
+                variant="subtle"
+                component="a"
+                href="https://homarr.dev/docs/management/workshop"
+                target="_blank"
+              >
                {t("action.website")}
              </Button>
            </Group>
@@ -269,6 +300,18 @@ function WorkshopBrowserContent({ initialType = "all", lockedType, onUse, useLab
              </Text>
            </Group>
            <Text>{selected.description}</Text>
+            {selected.screenshots.length > 0 && (
+              <SimpleGrid cols={{ base: 1, sm: 2 }}>
+                {selected.screenshots.map((screenshot, index) => (
+                  <Image
+                    key={screenshot}
+                    src={client.fileUrl(selected.id, screenshot, "960x640")}
+                    radius="sm"
+                    alt={t("screenshotAlt", { title: selected.title, number: index + 1 })}
+                  />
+                ))}
+              </SimpleGrid>
+            )}
            <Alert icon={<IconAlertTriangle size={18} />} color="yellow">
              {t("safety.inspect")}
            </Alert>
@@ -1,4 +1,26 @@
-FROM alpine:3.22 AS download
+# syntax=docker/dockerfile:1.10
+
+FROM node:24.18.0-alpine AS website
+WORKDIR /app
+
+RUN corepack enable pnpm
+COPY pnpm-lock.yaml pnpm-workspace.yaml package.json turbo.json ./
+COPY patches ./patches
+RUN --mount=type=cache,id=workshop-pnpm-store,target=/pnpm/store \
+    pnpm config set store-dir /pnpm/store && \
+    pnpm --config.node-linker=isolated fetch --ignore-scripts && \
+    rm -rf node_modules
+
+COPY apps/docs ./apps/docs
+COPY packages/definitions ./packages/definitions
+COPY packages/validation ./packages/validation
+COPY packages/workshop ./packages/workshop
+COPY tooling/typescript ./tooling/typescript
+RUN --mount=type=cache,id=workshop-pnpm-store,target=/pnpm/store \
+    pnpm install --recursive --offline --frozen-lockfile && \
+    CI=true SKIP_ENV_VALIDATION=true pnpm turbo build --filter=@homarr/docs
+
+FROM alpine:3.22 AS pocketbase

 ARG TARGETARCH
 ARG POCKETBASE_VERSION=0.39.6
@@ -20,10 +42,15 @@ RUN case "${TARGETARCH}" in \
 FROM alpine:3.22

 RUN apk add --no-cache ca-certificates tzdata && addgroup -S pocketbase && adduser -S -G pocketbase pocketbase
-COPY --from=download /out/pocketbase /usr/local/bin/pocketbase
-COPY entrypoint.sh /usr/local/bin/workshop-entrypoint
+COPY --from=pocketbase /out/pocketbase /usr/local/bin/pocketbase
+COPY --from=website /app/apps/docs/build /pb_public
+COPY apps/workshop/entrypoint.sh /usr/local/bin/workshop-entrypoint
+COPY apps/workshop/pb_hooks /pb_hooks
+COPY apps/workshop/pb_migrations /pb_migrations

-RUN chmod +x /usr/local/bin/workshop-entrypoint && mkdir -p /pb_data /pb_hooks /pb_migrations && chown -R pocketbase:pocketbase /pb_data /pb_hooks /pb_migrations
+RUN chmod +x /usr/local/bin/workshop-entrypoint && \
+    mkdir -p /pb_data && \
+    chown -R pocketbase:pocketbase /pb_data /pb_hooks /pb_migrations /pb_public

 USER pocketbase
 EXPOSE 8090
@@ -0,0 +1,19 @@
+**
+!package.json
+!pnpm-lock.yaml
+!pnpm-workspace.yaml
+!turbo.json
+!patches/**
+!apps/docs/**
+!apps/workshop/entrypoint.sh
+!apps/workshop/pb_hooks/**
+!apps/workshop/pb_migrations/**
+!packages/definitions/**
+!packages/validation/**
+!packages/workshop/**
+!tooling/typescript/**
+**/node_modules
+**/.docusaurus
+**/build
+**/dist
+**/.turbo
@@ -1,21 +1,21 @@
-# Homarr Workshop backend
+# Homarr Workshop service

-PocketBase provides the central Workshop API at `workshop.homarr.dev`. It is not a per-instance Homarr service. Local deployment is for development and integration testing.
+The Workshop image serves the compiled Homarr documentation and the PocketBase community API from one origin: `https://homarr.dev`. It is not a per-instance Homarr service. Local deployment is for development and integration testing.

 ## Local startup

 1. Copy the repository-root `.env.example` to `.env` and create a GitHub OAuth app.
 2. Set its callback URL to `http://localhost:<PB_EXPOSE_PORT>/api/oauth2-redirect` (port `8090` by default).
 3. Set `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `PB_SUPERUSER_EMAIL`, and `PB_SUPERUSER_PASSWORD`.
-4. Run `pnpm dev:workshop` from the repository root. It starts PocketBase and the Docusaurus Workshop together and removes obsolete Compose containers.
+4. Run `pnpm dev:workshop` from the repository root. It builds the single Workshop image, starts it, and removes obsolete Compose containers.

-Open the Workshop at `http://localhost:3003/workshop`. The API is at `http://localhost:<PB_EXPOSE_PORT>` and the emergency PocketBase dashboard is at `http://localhost:<PB_EXPOSE_PORT>/_/` (port `8090` by default). `0.0.0.0` in PocketBase's server log is its container bind address, not a browser URL. Day-to-day moderation belongs in `/workshop/admin`, not the PocketBase dashboard.
+Open the Workshop at `http://localhost:<PB_EXPOSE_PORT>/workshop`. The API is at `/api` on the same origin and the emergency PocketBase dashboard is at `/_/` (port `8090` by default). `0.0.0.0` in PocketBase's server log is its container bind address, not a browser URL. Day-to-day moderation belongs in `/workshop/admin`, not the PocketBase dashboard.

-Use `pnpm dev:workshop:backend` when only the API is needed. All Workshop configuration is read from the repository-root `.env`; there is no app-specific environment file. If port 8090 is unavailable, set `PB_EXPOSE_PORT` there. The website derives its local API URL from that port unless `WORKSHOP_API_URL` is explicitly set.
+All Workshop configuration is read from the repository-root `.env`; there is no app-specific environment file. If port 8090 is unavailable, set `PB_EXPOSE_PORT` there. `pnpm dev:workshop:website` remains available for Docusaurus HMR and connects to the local container through `WORKSHOP_API_URL`.

-The image downloads the official PocketBase `0.39.6` release and verifies it against that release's `checksums.txt`. Migrations and hooks are mounted read-only.
+The multi-stage image builds Docusaurus, downloads the official PocketBase `0.39.6` release, verifies it against that release's `checksums.txt`, and copies the versioned migrations, hooks, and static website into the runtime image.

-GitHub OAuth configuration is synchronized from the environment on every boot, including for an existing development volume. Local CORS is restricted to the documented Homarr and Docusaurus origins in `PB_ALLOWED_ORIGINS`; production must set it to `https://homarr.dev`.
+GitHub OAuth configuration is synchronized from the environment on every boot, including for an existing development volume. `PB_ALLOWED_ORIGINS` defaults to `*` because arbitrary self-hosted Homarr origins consume the central API. PocketBase authenticates writes with bearer tokens and does not use cookies; CORS is not an authorization boundary.

 ## Roles and account states

@@ -41,6 +41,7 @@ Restore only into the same PocketBase version after preserving the current volum

 ## Production checklist

+- Run `ghcr.io/homarr-labs/workshop:dev` behind the `homarr.dev` TLS endpoint; the image owns both the website and `/api`.
 - Terminate TLS at the reverse proxy and forward the real client IP.
 - Keep superuser credentials outside Compose and rotate them after bootstrap.
 - Restrict the dashboard path to operators; GitHub users never need it.
@@ -3,24 +3,23 @@ name: homarr-workshop
 services:
  workshop:
    build:
-      context: .
+      context: ../..
+      dockerfile: apps/workshop/Dockerfile
      args:
        POCKETBASE_VERSION: 0.39.6
-    image: homarr/workshop-pocketbase:0.39.6
+    image: homarr/workshop:0.39.6
    restart: unless-stopped
    environment:
      GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID:-}
      GITHUB_CLIENT_SECRET: ${GITHUB_CLIENT_SECRET:-}
      PB_SUPERUSER_EMAIL: ${PB_SUPERUSER_EMAIL:-}
      PB_SUPERUSER_PASSWORD: ${PB_SUPERUSER_PASSWORD:-}
-      PB_PUBLIC_URL: http://localhost:${PB_EXPOSE_PORT:-8090}
-      PB_ALLOWED_ORIGINS: ${PB_ALLOWED_ORIGINS:-http://localhost:3000,http://127.0.0.1:3000,http://localhost:3003,http://127.0.0.1:3003,http://localhost:7575,http://127.0.0.1:7575}
+      PB_PUBLIC_URL: ${PB_PUBLIC_URL:-http://localhost:${PB_EXPOSE_PORT:-8090}}
+      PB_ALLOWED_ORIGINS: ${PB_ALLOWED_ORIGINS:-*}
    ports:
      - "127.0.0.1:${PB_EXPOSE_PORT:-8090}:8090"
    volumes:
      - workshop_data:/pb_data
-      - ./pb_hooks:/pb_hooks:ro
-      - ./pb_migrations:/pb_migrations:ro
    security_opt:
      - no-new-privileges:true

@@ -5,12 +5,14 @@ if [ -n "${PB_SUPERUSER_EMAIL:-}" ] && [ -n "${PB_SUPERUSER_PASSWORD:-}" ]; then
  pocketbase superuser upsert "${PB_SUPERUSER_EMAIL}" "${PB_SUPERUSER_PASSWORD}" --dir=/pb_data
 fi

-echo "Workshop API: ${PB_PUBLIC_URL:-http://localhost:8090}"
-echo "Workshop website: http://localhost:3003/workshop"
+echo "Workshop: ${PB_PUBLIC_URL:-http://localhost:8090}/workshop"
+echo "Workshop API: ${PB_PUBLIC_URL:-http://localhost:8090}/api"

 exec pocketbase serve \
  --http=0.0.0.0:8090 \
-  --origins="${PB_ALLOWED_ORIGINS:-http://localhost:3000,http://127.0.0.1:3000,http://localhost:3003,http://127.0.0.1:3003,http://localhost:7575,http://127.0.0.1:7575}" \
+  --origins="${PB_ALLOWED_ORIGINS:-*}" \
  --dir=/pb_data \
  --hooksDir=/pb_hooks \
-  --migrationsDir=/pb_migrations
+  --migrationsDir=/pb_migrations \
+  --publicDir=/pb_public \
+  --indexFallback=true
@@ -14,7 +14,7 @@ Workshop behavior is defined once: one typed contract, one client, versioned Poc

 ## Baseline audit

-The abandoned prototype is preserved at `origin/feat/widget-store-prototype-backup` (`89260b875`). This rewrite starts at `dev` commit `ba7718bde`.
+The abandoned prototype is preserved at `origin/feat/widget-store-prototype-backup` (`89260b875`). This rewrite is rebased onto `dev` commit `93325642a`.

 | Area          | Severity | Baseline finding                                                                                                                    | V2 resolution                                                                                                      |
 | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
@@ -36,7 +36,8 @@ The abandoned prototype is preserved at `origin/feat/widget-store-prototype-back
 - Launch content: custom widgets (`homarr-custom-widget-v2`) and CSS (`homarr-custom-css-v1`).
 - Identity: GitHub OAuth only.
 - Community features: votes and reports; comments are removed.
- Hosting: one Homarr-operated service at `workshop.homarr.dev`; overrides are development-only.
+- Hosting: one Homarr-operated image and origin at `homarr.dev`; PocketBase serves both compiled docs and `/api`.
+- Resilience: the public shell and successfully loaded query data are cached independently; the rest of Homarr never depends on Workshop availability.
 - Publishing: immediate, with source inspection, reporting, and staff removal.
 - Staff: GitHub-authenticated moderators/admins use `/workshop/admin`; PocketBase superusers are bootstrap/emergency access.

@@ -52,6 +53,7 @@ The abandoned prototype is preserved at `origin/feat/widget-store-prototype-back
 - [x] Website and app implement loading, empty, offline, validation, permission, and destructive-action states.
 - [x] Keyboard semantics, mobile layout, dark mode, reduced motion, and horizontal overflow received a browser smoke test.
 - [x] Clean PocketBase startup, migration, health, backup, and restore procedures are reproducible and documented.
+- [x] Documentation and Workshop API are built into one reproducible image and served from `homarr.dev` without production cross-origin requests.
 - [ ] Add automated authenticated cross-surface E2E coverage before changing the PR from draft to ready.

 ## Deferred after V2
@@ -64,7 +66,7 @@ The baseline has three P0, seven P1, and one P2 findings. The rewrite closes eve

 | Gate                        | Result  | Evidence                                                                                                                                                                                          |
 | --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Branch ancestry             | Pass    | Rebuilt from `dev` at `ba7718bde`; prototype preserved at `origin/feat/widget-store-prototype-backup`.                                                                                            |
+| Branch ancestry             | Pass    | Rebuilt from `dev` at `93325642a`; prototype preserved at `origin/feat/widget-store-prototype-backup`.                                                                                            |
 | Contract                    | Pass    | Five Vitest cases cover widget/CSS fixtures, filenames, limits, screenshot validation, and round trips.                                                                                           |
 | Backend                     | Pass    | Disposable PocketBase integration matrix covers roles, account states, ownership forgery, schema rejection, duplicate votes, private reports, escalation, deletion cascades, and audit snapshots. |
 | Backend operations          | Pass    | PocketBase 0.39.6 runs unprivileged and builds with checksum verification; clean boot and a cloned legacy SQLite volume both migrate and become healthy.                                          |
@@ -72,7 +74,7 @@ The baseline has three P0, seven P1, and one P2 findings. The rewrite closes eve
 | Lint                        | Pass    | Scoped lint exits clean; remaining warnings predate the rewrite. Workshop has zero warnings.                                                                                                      |
 | Format                      | Pass    | Every changed supported file passes `oxfmt --check`; repository-wide Docs formatting still reports pre-existing drift.                                                                            |
 | Production builds           | Pass    | Docusaurus and Next.js production builds pass under Node 24.18.0.                                                                                                                                 |
-| Browser smoke               | Pass    | Desktop/mobile discovery and the disconnected API state render without uncaught errors; cached data remains readable and retry is explicit.                                                       |
+| Browser smoke               | Pass    | Desktop/mobile discovery, disconnected API recovery, and a first-visit online-to-offline reload render without uncaught errors.                                                                   |
 | Automated cross-surface E2E | Open P1 | Authenticated website-to-Homarr publish/install and moderator flows still need browser automation.                                                                                                |

 Final implementation scores (10 is best): security 9, architecture/DX 9, moderation 9, performance 9, responsive UI 9, theming 9, accessibility 8, automated testing 7. Accessibility remains below 9 until authenticated dialogs and destructive flows receive a full keyboard/screen-reader pass.
@@ -21,7 +21,7 @@
    "db:studio": "pnpm -F db studio",
    "dev": "pnpm -F nextjs dev",
    "dev:docs": "pnpm -F @homarr/docs dev",
-    "dev:workshop": "concurrently --kill-others --names workshop-api,workshop-web \"pnpm dev:workshop:backend\" \"pnpm dev:workshop:website\"",
+    "dev:workshop": "pnpm dev:workshop:backend",
    "dev:workshop:backend": "docker compose --env-file .env -f apps/workshop/docker-compose.yml up --build --remove-orphans",
    "dev:workshop:website": "pnpm -F @homarr/workshop build && pnpm -F @homarr/docs clear && pnpm with-env sh -c 'WORKSHOP_API_URL=${WORKSHOP_API_URL:-http://localhost:${PB_EXPOSE_PORT:-8090}} pnpm -F @homarr/docs dev'",
    "docker:dev": "docker compose -f ./development/development.docker-compose.yml up",
@@ -4461,6 +4461,15 @@
  "workshop": {
    "title": "Workshop",
    "loading": "Loading submission",
+    "intro": {
+      "title": "Community Workshop",
+      "description": "Discover widgets and CSS themes made by other Homarr users. Inspect the source before bringing anything into this instance."
+    },
+    "status": {
+      "connected": "Connected",
+      "offline": "Saved catalog"
+    },
+    "screenshotAlt": "{title} screenshot {number}",
    "by": "By {name} · revision {revision}",
    "type": {
      "widget": "Widget",
@@ -15,6 +15,7 @@ import type {

 import {
  WORKSHOP_API_URL,
+  WORKSHOP_REQUEST_TIMEOUT_MS,
  WorkshopError,
  schemaVersionForType,
  workshopAccountStateSchema,
@@ -58,6 +59,9 @@ const errorCodeForStatus = (status: number) => {
  return "unknown" as const;
 };

+const workshopRequestSignal = (signal?: AbortSignal) =>
+  AbortSignal.any(signal ? [signal, AbortSignal.timeout(WORKSHOP_REQUEST_TIMEOUT_MS)] : [AbortSignal.timeout(WORKSHOP_REQUEST_TIMEOUT_MS)]);
+
 const asWorkshopError = (error: unknown, fallback: string) => {
  if (error instanceof WorkshopError) return error;
  if (error instanceof ClientResponseError) {
@@ -75,6 +79,9 @@ const asWorkshopError = (error: unknown, fallback: string) => {
  if (error instanceof TypeError) {
    return new WorkshopError("unavailable", fallback);
  }
+  if (error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
+    return new WorkshopError("unavailable", `${fallback}. The request timed out.`);
+  }
  return new WorkshopError("unknown", error instanceof Error ? error.message : fallback);
 };

@@ -150,7 +157,7 @@ export class WorkshopClient {
        .getList(options.page ?? 1, options.perPage ?? 24, {
          filter: filters.join(" && "),
          sort: options.sort === "newest" ? "-created" : "-score,-created",
-          signal: options.signal,
+          signal: workshopRequestSignal(options.signal),
        });
      return { ...result, items: result.items.map((item) => workshopSubmissionSummarySchema.parse(item)) };
    } catch (error) {
@@ -161,7 +168,7 @@ export class WorkshopClient {
  async get(id: string, signal?: AbortSignal): Promise<WorkshopSubmissionDetail> {
    try {
      return workshopSubmissionDetailSchema.parse(
-        await this.pocketBase.collection("submissions").getOne(id, { signal }),
+        await this.pocketBase.collection("submissions").getOne(id, { signal: workshopRequestSignal(signal) }),
      );
    } catch (error) {
      throw asWorkshopError(error, "Submission not found");
@@ -57,6 +57,8 @@ describe("Workshop contracts", () => {
    expect(schemaVersionForType("widget")).toBe(WIDGET_SCHEMA_VERSION);
    expect(schemaVersionForType("css")).toBe(CSS_SCHEMA_VERSION);
    expect(workshopExportFilename("My / Theme!", "css")).toBe("my-theme.css");
+    expect(workshopExportFilename("---My---Widget---", "widget")).toBe("my-widget.json");
+    expect(workshopExportFilename("-".repeat(100_000), "css")).toBe("homarr-workshop.css");
  });

  it("validates screenshot count, MIME type, and size", () => {
@@ -1,7 +1,7 @@
 import { customWidgetImportSchema } from "@homarr/validation/custom-widget";
 import { z } from "zod";

-export const WORKSHOP_API_URL = "https://workshop.homarr.dev";
+export const WORKSHOP_API_URL = "https://homarr.dev";
 export const WORKSHOP_WEB_URL = "https://homarr.dev/workshop";
 export const WIDGET_SCHEMA_VERSION = "homarr-custom-widget-v2";
 export const CSS_SCHEMA_VERSION = "homarr-custom-css-v1";
@@ -9,6 +9,7 @@ export const MAX_CSS_LENGTH = 16_384;
 export const MAX_CONTENT_LENGTH = 1_000_000;
 export const MAX_SCREENSHOTS = 5;
 export const MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+export const WORKSHOP_REQUEST_TIMEOUT_MS = 8_000;
 export const WORKSHOP_SCREENSHOT_MIME_TYPES = ["image/png", "image/jpeg", "image/webp"] as const;

 export const workshopSubmissionTypeSchema = z.enum(["widget", "css"]);
@@ -165,11 +166,21 @@ export const schemaVersionForType = (type: WorkshopSubmissionType) =>
  type === "widget" ? WIDGET_SCHEMA_VERSION : CSS_SCHEMA_VERSION;

 export function workshopExportFilename(title: string, type: WorkshopSubmissionType) {
-  const safeTitle =
-    title
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9_-]+/g, "-")
-      .replace(/^-+|-+$/g, "") || "homarr-workshop";
+  let safeTitle = "";
+  let separatorPending = false;
+
+  for (const character of title.trim().toLowerCase()) {
+    const isLetter = character >= "a" && character <= "z";
+    const isNumber = character >= "0" && character <= "9";
+    if (isLetter || isNumber || character === "_") {
+      if (separatorPending && safeTitle.length > 0) safeTitle += "-";
+      safeTitle += character;
+      separatorPending = false;
+    } else {
+      separatorPending = safeTitle.length > 0;
+    }
+  }
+
+  safeTitle ||= "homarr-workshop";
  return `${safeTitle}.${type === "widget" ? "json" : "css"}`;
 }
@@ -2738,7 +2738,7 @@ importers:
        version: 0.28.0
      typescript:
        specifier: 'catalog:'
-        version: 6.0.3
+        version: 7.0.2

  tooling/github: {}