From 2a979c2eca6d8de7cfebf99de4c62b54c8d6e908 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Sun, 21 Jun 2026 22:23:32 -0400
Subject: [PATCH] =?UTF-8?q?docs(deploy):=20record=20release-channel=20?=
 =?UTF-8?q?=E2=86=92=20Vercel=20project=20promotion=20+=20on-demand=20depl?=
 =?UTF-8?q?oy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captures the 3-project mapping (bitvid-unstable/beta/bitvid → unstable.bitvid.network
/ bitvid-beta.vercel.app / bitvid.network), the vercel.json knobs (npm install pin,
deploymentEnabled.unstable), the promotion git steps (merge unstable→beta taking
unstable's tree, ff main), per-project on-demand deploy commands, and the
version-marker verification + soak-skip caveat.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/deployment-notes.md | 69 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/docs/deployment-notes.md b/docs/deployment-notes.md
index 5a1dc95b..7579d804 100644
--- a/docs/deployment-notes.md
+++ b/docs/deployment-notes.md
@@ -12,3 +12,72 @@
 - Keep source HTML entry points (`index.html`, `embed.html`) pointing at logical asset paths (for example, `js/index.js` and `css/tailwind.generated.css`). The build pipeline rewrites those references to content-hashed filenames in `dist/`.
 - Deploy pipelines should always purge HTML entrypoints (`/` + `/index.html` and `/embed.html`) at the edge after publish so clients do not keep serving stale source shells.
 - App routing query parameters (such as `?v=` for video pointers) are unchanged and remain part of runtime URL behavior.
+
+## Release channels → Vercel projects (promotion + on-demand deploy)
+
+The three release branches each map to a **separate Vercel project** under the
+`pr0m3th3ans-projects` team:
+
+| Branch     | Vercel project    | Live URL                  |
+|------------|-------------------|---------------------------|
+| `unstable` | `bitvid-unstable` | `unstable.bitvid.network` |
+| `beta`     | `bitvid-beta`     | `bitvid-beta.vercel.app`  |
+| `main`     | `bitvid`          | `bitvid.network` (prod)   |
+
+The repo's local `.vercel/project.json` is normally linked to **`bitvid-unstable`**
+so day-to-day `vercel deploy --prod` targets the unstable site.
+
+### vercel.json knobs
+- `installCommand: "npm install"` is pinned because both `package-lock.json` and
+  `pnpm-lock.yaml` exist; without the pin Vercel auto-selects pnpm and the build
+  fails on the unstable/beta projects.
+- `git.deploymentEnabled.unstable: false` disables auto-deploy for a branch named
+  `unstable`. It only affects that branch key, so it's harmless on the beta/main
+  projects (they deploy `beta`/`main`). The bitvid-beta/bitvid projects ARE
+  git-connected, so a push to `beta`/`main` also auto-triggers a build — explicit
+  CLI deploys (below) just make the result deterministic.
+
+### Promotion (unstable → beta → main)
+`unstable` is the integration branch. `main` is usually a clean ancestor
+(fast-forward). `beta` can carry an extra superseded commit (e.g. an old
+`vercel.json` pin), so prefer a merge that takes unstable's tree:
+
+```bash
+# beta: merge unstable, preferring unstable on conflict; verify trees match
+git checkout beta && git reset --hard origin/beta
+git merge origin/unstable -X theirs --no-edit -m "Promote unstable → beta: <summary>"
+git diff --quiet origin/unstable HEAD && echo "beta tree == unstable"   # expect 0
+git push origin beta
+
+# main: fast-forward to unstable
+git checkout main && git reset --hard origin/main
+git merge --ff-only origin/unstable
+git push origin main
+```
+
+### Build/deploy each project (on-demand)
+```bash
+# beta
+vercel link --yes --project bitvid-beta && vercel deploy --prod --yes
+# production
+vercel link --yes --project bitvid && vercel deploy --prod --yes   # aliases to bitvid.network
+# restore the day-to-day link
+vercel link --yes --project bitvid-unstable
+```
+
+### Verify
+The footer version marker (`v: <8hex> • <date>`) is content-hash based; all three
+projects build from the same source in the same Vercel env, so the markers should
+**match each other** after a promotion. Verify per domain and confirm a known new
+module is served, e.g.:
+
+```bash
+for host in unstable.bitvid.network bitvid-beta.vercel.app bitvid.network; do
+  echo -n "$host : "; curl -s "https://$host/index.html?cb=$(date +%s)" \
+    | grep -oE 'v: [0-9a-f]{8} • [0-9-]+' | head -1
+done
+```
+
+> Caveat: promoting a large batch straight to `main` skips the `beta` soak. Do it
+> only deliberately; otherwise let changes soak on `beta` first. Rollback = redeploy
+> the previous `bitvid` production deployment (`vercel rollback` or redeploy by URL).