diff --git a/.github/workflows/promote-playground.yml b/.github/workflows/promote-playground.yml
new file mode 100644
index 000000000..3f0fc0f26
--- /dev/null
+++ b/.github/workflows/promote-playground.yml
@@ -0,0 +1,35 @@
+name: Promote playground on tag
+
+on:
+  push:
+    tags:
+      - "@onflow/**"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: promote-playground
+  cancel-in-progress: false
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout with full history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Move playground branch to tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          TAG="${GITHUB_REF_NAME:-${GITHUB_REF##*/}}"
+          git fetch --tags
+          git show --no-patch --pretty=fuller "$TAG"
+
+          # Create/update branch at the tag commit and push
+          git branch -f playground "$TAG"
+          git push --force-with-lease origin playground
diff --git a/packages/demo/DEPLOY.md b/packages/demo/DEPLOY.md
new file mode 100644
index 000000000..f452fdafc
--- /dev/null
+++ b/packages/demo/DEPLOY.md
@@ -0,0 +1,53 @@
+# Playground Deployment Workflow
+
+## How It Works
+
+The `playground` branch always points to the latest release tag and is deployed to Vercel.
+
+**Key principle:** Playground = released version.
+
+## Automatic Sync
+
+### When
+
+- Automatically on every package release (e.g., `@onflow/fcl@1.2.3`)
+- Triggered by changesets when tags are created
+
+### What happens
+
+1. Workflow detects new release tag
+2. Force-updates playground branch to point at the tag
+3. Vercel deploys the tagged release
+
+## Emergency Hotfixes
+
+If demo needs urgent fix before next release:
+
+### Option 1: Patch Release
+
+Create a patch release for demo package only with changeset.
+
+### Option 2: Manual Fix
+
+```bash
+git checkout playground
+# Fix demo files only (packages/demo/**)
+git commit -m "fix(demo): emergency hotfix"
+git push origin playground
+```
+
+**Warning:** Next release will overwrite playground. Emergency fix MUST go in next release!
+
+## Rules
+
+### DO
+
+- Let the workflow handle normal releases
+- Create patch releases for important fixes
+- Only manually fix demo files (`packages/demo/**`)
+- Ensure emergency fixes go in next release
+
+### DON'T
+
+- Don't let emergency fixes skip the next release
+- Don't use manual fixes for non-critical issues