docs: describe the dev/master/release branching model and wire it from README and AGENTS.md

.claude/skills/electron-bump/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: electron-bump
-description: Upgrade the Electron version in Rocket.Chat.Electron safely. Detects breaking changes between the current and target Electron release, produces a migration plan gated on user approval, applies the fixes (using GitNexus impact analysis to find every affected callsite), bumps coupled config (electron-builder bundle id, CI node-version, @types/node), runs lint + tests, and opens a ready PR from a fresh branch off master. Trigger when the user says "bump electron", "upgrade electron", "update electron to X", "/electron-bump", or asks to move to a newer Electron release.
+description: Upgrade the Electron version in Rocket.Chat.Electron safely. Detects breaking changes between the current and target Electron release, produces a migration plan gated on user approval, applies the fixes (using GitNexus impact analysis to find every affected callsite), bumps coupled config (electron-builder bundle id, CI node-version, @types/node), runs lint + tests, and opens a ready PR from a fresh branch off dev. Trigger when the user says "bump electron", "upgrade electron", "update electron to X", "/electron-bump", or asks to move to a newer Electron release.
 ---
 
 # Electron Version Bump
@@ -19,7 +19,7 @@ Automates a safe Electron upgrade for **this repo** (Rocket.Chat.Electron). Plan
 
 ## Hard rules
 
-- Branch from **master**, never edit master directly. Use a worktree (see CLAUDE.md § Worktrees) so the user's working dir is untouched.
+- Branch from **dev**, never edit dev directly. Use a worktree (see CLAUDE.md § Worktrees) so the user's working dir is untouched.
 - Plan-gated: do NOT apply any code/config edit until the user approves the migration plan.
 - This is an Orchestrator task: delegate research to `researcher`, edits to `builder-*`, test runs to `watcher`/`tester`. Don't solo the implementation.
 - Never commit/push without explicit user permission for the commit step (PR creation is the approved end-state of this skill, but confirm before `git push` if not already authorized this session).
@@ -118,10 +118,10 @@ Write the plan to a **dedicated, non-colliding** file: `.localdev/workflow/elect
 
 ## Phase 4 — Branch & apply (after approval)
 
-1. Create worktree off master:
+1. Create worktree off dev:
    ```bash
    mkdir -p ../Rocket.Chat.Electron-worktrees
-   git worktree add ../Rocket.Chat.Electron-worktrees/electron-<TARGET> -b chore/electron-<TARGET> master
+   git worktree add ../Rocket.Chat.Electron-worktrees/electron-<TARGET> -b chore/electron-<TARGET> dev
    ```
    Work in that worktree for the rest of the skill.
 2. Bump the version:
@@ -155,7 +155,7 @@ Definition of Done: version bumped everywhere the plan listed, lint green, tests
 2. Show the user the diff summary, confirm the commit.
 3. Commit with conventional message: `chore: update Electron from <CURRENT> to <TARGET>` — match the repo's historical style (see PRs #3285, #3179; the PR number isn't known at commit time, and squash-merge titles carry it anyway). Body lists breaking-change adaptations for a major bump; minimal for patch/minor.
 4. Push the branch.
-5. Open a **ready (non-draft)** PR: `gh pr create --base master --label build-artifacts`. Base is **master** (repo default). Apply the `build-artifacts` label here because an Electron bump changes packaging and reviewers must smoke-test the built installers — this is exactly the case the label is for. PR body:
+5. Open a **ready (non-draft)** PR: `gh pr create --base dev --label build-artifacts`. Base is **dev** (repo default). Apply the `build-artifacts` label here because an Electron bump changes packaging and reviewers must smoke-test the built installers — this is exactly the case the label is for. PR body:
    - What changed: version delta, bundled Node/Chromium.
    - Breaking changes addressed (bullet list, frame as adaptation not regression).
    - Verification: lint + tests pass; CI will run cross-platform builds.

.github/CONTRIBUTING.md

@@ -29,6 +29,17 @@ To check your files, run:
 yarn lint
 ```
 
+## Branching Model
+
+Pull requests target `dev`, the default branch. `master` holds only
+released code — it only moves forward via a `dev`→`master` release merge.
+`release/X.Y.x` branches are patch lines for a shipped stable version,
+maintained by cherry-picking fixes from `dev`; only backport PRs for an
+already-released version should target one of these.
+
+See `docs/development-and-release-flow.md` for the full picture of how a
+change moves from PR to release.
+
 ## Contributor License Agreement
 
 Please review and sign our [CLA].

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,6 +4,9 @@ prefixes:
 
 - "feat:" for new features;
 - "fix:" for bug fixes.
+
+INSTRUCTION: Target the `dev` branch, unless this PR is backporting a fix
+to a `release/X.Y.x` patch line.
 -->
 
 <!-- Inform the issue number that this PR closes, or remove the line below -->

AGENTS.md

@@ -26,13 +26,37 @@ yarn workspaces:build        # Build all workspaces
   `rm -rf workspaces/desktop-release-action/dist/dist` — the action only
   needs `workspaces/desktop-release-action/dist/index.js`.
 
+## Branching Model
+
+- `dev` is the default branch. ALL feature and fix PRs target `dev` and are
+  squash-merged.
+- `master` holds only released code. It advances only via a `dev`→`master`
+  release PR merged with a true merge commit (`gh pr merge --merge`) —
+  NEVER squash a release PR; squashing forks history permanently.
+- `release/X.Y.x` branches are patch lines for a shipped stable version.
+  Fixes land on `dev` first and are cherry-picked onto the release branch.
+  A hotfix authored directly on a release branch must be forward-ported to
+  `dev` immediately via a cherry-pick PR.
+- Never back-merge `master` or a `release/X.Y.x` branch into `dev`.
+- Tags are created only via `yarn release:tag` (channel-aware guard).
+  Release builds trigger on semver tag pushes only and always produce a
+  draft release for a human to review and publish.
+- Version invariant: `package.json` on `dev` always equals the newest tag
+  cut from `dev`'s own line (the first alpha of a new cycle bumps straight
+  to `X.(Y+1).0-alpha.1`).
+- Details: `docs/development-and-release-flow.md` (conceptual overview),
+  `docs/release-process.md` (exact commands).
+
 ## Patches And Builds
 
 - Do not confuse the two patch systems:
   - Yarn patch protocol: `.yarn/patches/`, currently for `@ewsjs/xhr`
     (configured in `package.json`).
   - `patch-package`: `patches/`, currently for `@kayahr/jest-electron-runner`.
 - Never add `@ewsjs/xhr` patches to `patches/`; that creates CI conflicts.
+- The `desktop-release-action`'s dev/snapshot code paths (`releaseDevelopment`
+  / `releaseSnapshot`) are intentionally dead — do not rebuild its `dist/`
+  bundle just to remove them.
 - Windows builds must include all architectures: `x64`, `ia32`, and `arm64`.
 - Code signing uses Google Cloud KMS in two phases:
   1. Build packages without signing (empty env vars).
@@ -209,8 +233,8 @@ node qa/scripts/export-qase-csv.mjs qa/<pack>
 
 - Never commit or push without explicit user permission — "fix this" does NOT
   mean "commit it".
-- Never commit directly to `master` or `dev` — create a branch, test, open a
-  PR.
+- Never commit directly to `master`, `dev`, or `release/X.Y.x` — create a
+  branch, test, open a PR.
 - Read-only git operations (status, diff, log) are always fine.
 - Show what will be committed before committing.
 
@@ -220,7 +244,7 @@ Use worktrees to avoid disrupting another working directory:
 
 ```bash
 mkdir -p ../Rocket.Chat.Electron-worktrees
-git worktree add ../Rocket.Chat.Electron-worktrees/feature-name -b new-branch master
+git worktree add ../Rocket.Chat.Electron-worktrees/feature-name -b new-branch dev
 ```
 
 ### Working Principles
@@ -266,7 +290,7 @@ This project is indexed by GitNexus as **Rocket.Chat.Electron**. Use the GitNexu
 ## Always Do
 
 - **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "master"})`.
+- **MUST run `detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. For regression review, compare against the default branch: `detect_changes({scope: "compare", base_ref: "dev"})`.
 - **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
 - When exploring unfamiliar code, use `query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `context({name: "symbolName"})`.

README.md

@@ -1,6 +1,6 @@
 # Rocket.Chat Desktop App
 
-[![Build Status](https://github.com/RocketChat/Rocket.Chat.Electron/actions/workflows/build-release.yml/badge.svg)](https://github.com/RocketChat/Rocket.Chat.Electron/actions)
+[![Latest release](https://img.shields.io/github/v/release/RocketChat/Rocket.Chat.Electron)](https://github.com/RocketChat/Rocket.Chat.Electron/releases/latest)
 ![Project Dependencies](https://img.shields.io/librariesio/github/RocketChat/Rocket.Chat.Electron)
 [![GitHub All Releases](https://img.shields.io/github/downloads/RocketChat/Rocket.Chat.Electron/total.svg)](https://github.com/RocketChat/Rocket.Chat.Electron/releases/latest)
 ![GitHub](https://img.shields.io/github/license/RocketChat/Rocket.Chat.Electron.svg)
@@ -155,6 +155,21 @@ command on. Ready for distribution file will be outputted to `dist` directory.
 All packaging actions are handled by [electron-builder][]. It has a lot of
 [customization options][].
 
+## Development and Releases
+
+All pull requests target `dev`; `master` contains only released code, and
+`release/X.Y.x` branches carry patch releases for a shipped version.
+Releases are tag-driven — pushing a semver tag triggers CI to build every
+platform and draft a GitHub release, which a human then reviews and
+publishes.
+
+- [docs/development-and-release-flow.md][] — conceptual overview of the
+  branch model, versioning, and CI/CD.
+- [docs/release-process.md][] — operational runbook with the exact commands
+  for cutting alpha, stable, and patch releases.
+- [.github/CONTRIBUTING.md][] — contribution guidelines, including which
+  branch to target.
+
 ## Default servers
 
 The `servers.json` file will define what servers the client will connect to and
@@ -265,3 +280,6 @@ Released under the MIT license.
 [Jest electron runner]: https://github.com/kayahr/jest-electron-runner
 [electron-builder]: https://github.com/electron-userland/electron-builder
 [customization options]: https://www.electron.build/configuration
+[docs/development-and-release-flow.md]: docs/development-and-release-flow.md
+[docs/release-process.md]: docs/release-process.md
+[.github/CONTRIBUTING.md]: .github/CONTRIBUTING.md

docs/COVERAGE.md

@@ -7,7 +7,7 @@ Running log of test-coverage milestones for Rocket.Chat.Electron. Append a new r
 - `yarn test:coverage` runs the full Jest suite with `--coverage` and writes reports to `coverage/` (`lcov.info`, `coverage-summary.json`, plus a `text-summary` to the console).
 - Two Jest projects run under `@kayahr/jest-electron-runner`: renderer (electron DOM env) and main (node env). Coverage is collected across both via the root-level `collectCoverageFrom` in `jest.config.js`.
 - The authoritative number is `coverage/coverage-summary.json` → `total.lines.pct` (the console `text-summary` matches it).
-- CI (`.github/workflows/validate-pr.yml`) runs `yarn test:coverage` on every PR to `master`/`dev` and uploads to **Codecov** (`unit` flag). Coverage is **informational** — there is intentionally no hard `coverageThreshold` gate, matching the main Rocket.Chat monorepo's house style (`codecov.yml`: `patch: off`, project `target: auto / threshold: 1%`).
+- CI (`.github/workflows/validate-pr.yml`) runs `yarn test:coverage` on every PR to `dev`, `master`, or a `release/*` line and uploads to **Codecov** (`unit` flag). Coverage is **informational** — there is intentionally no hard `coverageThreshold` gate, matching the main Rocket.Chat monorepo's house style (`codecov.yml`: `patch: off`, project `target: auto / threshold: 1%`).
 
 ## How to update this log