From 56b146b54d3adf7db26a8b2230d287d8208f1f51 Mon Sep 17 00:00:00 2001
From: ajnart <thomas@ajnart.dev>
Date: Sun, 30 Aug 2026 22:06:10 +0200
Subject: [PATCH] fix: harden v2 release preparation

---
 .github/workflows/deployment-docker-image.yml |  2 +-
 .mcp.json                                     |  2 +-
 apps/docs/README.md                           |  3 +-
 apps/docs/docs/workshop/operator.mdx          | 33 +++++++++++++++++--
 4 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/deployment-docker-image.yml b/.github/workflows/deployment-docker-image.yml
index b7cd921c3..14135e7f8 100644
--- a/.github/workflows/deployment-docker-image.yml
+++ b/.github/workflows/deployment-docker-image.yml
@@ -38,7 +38,7 @@ jobs:
       SKIP_RELEASE: ${{ github.event_name == 'workflow_dispatch' || github.ref_name == 'dev' || github.ref_name == 'next' }}
     outputs:
       version: ${{ steps.read-semver.outputs.version || steps.version-fallback.outputs.version }}
-      git_ref: ${{ steps.read-git-ref.outputs.ref || github.ref }}
+      git_ref: ${{ steps.read-git-ref.outputs.ref || steps.read-semver.outputs.version || github.ref }}
       skipped: ${{ env.SKIP_RELEASE }}
     steps:
       - run: echo "Manual dispatch redeploys the latest existing release without creating a new one"
diff --git a/.mcp.json b/.mcp.json
index 6636fc5c1..c6e3c4bb4 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -2,7 +2,7 @@
   "mcpServers": {
     "mantine": {
       "command": "npx",
-      "args": ["-y", "@mantine/mcp-server"]
+      "args": ["-y", "@mantine/mcp-server@9.5.2"]
     }
   }
 }
diff --git a/apps/docs/README.md b/apps/docs/README.md
index 863ff66ec..7646148aa 100644
--- a/apps/docs/README.md
+++ b/apps/docs/README.md
@@ -108,4 +108,5 @@ pnpm verify:search
 
 ## Contributing
 
-When making changes to the homarr codebase that affect user-facing behavior, **always update the corresponding documentation in this app**. See `.cursor/rules/documentation-sync.mdc` for the complete mapping of code changes to doc locations.
+When a Homarr change affects user-facing behavior, update the corresponding documentation in this app. See the
+[documentation-sync skill](../../.agents/skills/documentation-sync/SKILL.md) for the code-to-documentation mapping.
diff --git a/apps/docs/docs/workshop/operator.mdx b/apps/docs/docs/workshop/operator.mdx
index a43c53e1a..7ec1aac7b 100644
--- a/apps/docs/docs/workshop/operator.mdx
+++ b/apps/docs/docs/workshop/operator.mdx
@@ -127,5 +127,34 @@ GitHub OAuth requires both credentials and the callback `https://v2.preview.homa
 after changing environment values, then verify the health endpoint, `/workshop`, a public listing request, GitHub
 sign-in, and an installation from the Homarr preview.
 
-Back up application and PocketBase data before deployment. Publish the combined image by immutable digest, test the
-exact digest in staging, rehearse application rollback and PocketBase restore, then promote that same digest.
+## Backup and restore
+
+PocketBase data lives in `/pb_data`. Stop writes and copy it to a new, empty backup directory:
+
+```sh
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml stop workshop
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml cp workshop:/pb_data/. ./workshop-backup
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml start workshop
+```
+
+Restore only after preserving the current volume and confirming the backup contains `data.db`:
+
+```sh
+test -f ./workshop-backup/data.db
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml stop workshop
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml run --rm --no-deps --entrypoint sh workshop \
+  -c 'find /pb_data -mindepth 1 -maxdepth 1 -exec rm -rf {} +'
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml cp ./workshop-backup/. workshop:/pb_data
+docker compose --env-file apps/workshop/.env.staging \
+  -f apps/workshop/docker-compose.staging.yml start workshop
+curl --fail http://127.0.0.1:8090/api/health
+```
+
+The restore empties the selected volume. Rehearse it in staging, then verify sign-in and one installation. Publish by
+immutable digest, validate that exact digest in staging, and promote the same digest.