docs: document the dev/beta/main release lifecycle

CLAUDE.md and docs/release-channels.md now describe the full cycle: work
lands on feature/fix branches merged into dev, dev auto-publishes on every
push, beta is cut from dev as a frozen stabilization branch (also
auto-publishing on every push, fixes forwarded from fix/<issue> branches),
and after a quiet freeze period beta merges to main and gets tagged for
the actual stable release. Also fixes README's stale reference to
.github/workflows (actual CI lives under .forgejo/workflows) and links
out to the new CONTRIBUTING.md.

CLAUDE.md

@@ -1,19 +1,27 @@
-# CLAUDE.md — Repo hygiene (local only, not committed)
+# CLAUDE.md — Repo hygiene
 
 Scope: this file covers *repo hygiene* — branching, remotes, CI, cleanup. It is not project documentation.
 
 ## Branch model
-- `main` — release branch, always tag-ready. Don't commit directly to it.
-- `dev` — integration branch. Land day-to-day work here first.
-- Feature/fix work goes on short-lived branches off `dev` (`feature/x`, `fix/x`), merged back into `dev`, then `dev` → `main` when ready to release.
+- `main` — release branch, always tag-ready. Don't commit directly to it; the only thing that lands there is a `beta` merge (see release lifecycle below).
+- `dev` — integration branch. Land day-to-day work here first. Publishes a dev-track build automatically on every push (see CI below) — this is the "push, test, fix forward with another push" loop.
+- `beta` — frozen stabilization branch, cut from `dev`. Publishes a beta-track build automatically on every push, same as `dev`. While frozen, only `fix/<issue>` branches merged directly into `beta` should land there — `dev` keeps moving independently for the next cycle.
+- All new work — features and bug fixes alike — goes on short-lived branches: `feature/<name>` or `fix/<issue>`. Normally these branch off `dev` and merge back into `dev`. During a beta freeze, a fix for a beta-reported issue branches off `beta` instead, merges into `beta` to unblock testers, and should also be cherry-picked/merged into `dev` so the bug doesn't quietly regress there.
+
+## Release lifecycle
+1. Work lands on `dev` via `feature/x` / `fix/x` branches. Every push to `dev` auto-publishes a dev-track build (`bakery track set dev`) — test it, fix issues with another push to `dev`.
+2. Once `dev` has gone roughly **a week** without new issues, cut `beta` fresh from `dev`'s current tip: `git branch -f beta dev` (from a clean checkout — don't `git checkout main`/`git merge` for this, use a plain branch-pointer move), then force-push `beta` to both remotes. This freezes it.
+3. `beta` auto-publishes on every push, same as `dev`. Anyone can file issues against it on Forgejo. Fixes land via `fix/<issue>` → `beta` (and should be forwarded into `dev` too).
+4. Once `beta` has gone roughly **a month** without new issues, merge `beta` → `main`, then push a `vX.Y.Z` tag from `main` to actually cut the stable release (the merge alone triggers no CI — only the tag does). Reset `beta` fresh from `dev` again to start the next cycle.
 
 ## Remotes
 - `origin` — Forgejo (`git.breadway.dev` via Hestia, SSH) — authoritative.
 - `github` — GitHub mirror. Push both when publishing.
 
 ## CI
-- `.forgejo/workflows/package.yml`, `release-bakery.yml`, `release-bread-theme.yml` all trigger only on `push: tags: ['v*']` — pushing to `dev` or `main` runs nothing. Tag a release to trigger packaging.
-- No build/lint/test CI runs on ordinary commits or PRs — test locally before merging to `dev`/`main`.
+- `.forgejo/workflows/package.yml`, `release-bakery.yml`, `release-bread-theme.yml` all trigger only on `push: tags: ['v*']` — pushing to `dev`, `beta`, or `main` doesn't run these. Tag a release to trigger packaging.
+- `dev-bakery.yml` / `dev-bread-theme.yml` trigger on `push: branches: ['dev']`; `beta-bakery.yml` / `beta-bread-theme.yml` trigger on `push: branches: ['beta']` — both auto-publish a signed, auto-versioned build to `dl.breadway.dev/{dev,beta}/`. See `docs/release-channels.md` for the full three-track (stable/beta/dev) policy.
+- No build/lint/test CI runs on ordinary commits or PRs to `dev`/`beta` beyond what those track workflows do — there's no separate lint/PR-check pipeline.
 
 ## Cleanup
 - Delete feature/fix branches (local + remote) once merged. Check with `git branch --merged dev` / `git branch --merged main`.

README.md

@@ -123,8 +123,8 @@ bread-ecosystem/
 
 ## Release pipeline
 
-Each product repo (`Breadway/bread`, `Breadway/breadbar`, …) has a
-`.github/workflows/release.yml` that triggers on `v*` tags. The workflow
+Each product repo (`Breadway/bread`, `Breadway/breadbar`, …) has
+`.forgejo/workflows/release-*.yml` that triggers on `v*` tags. The workflow
 runs on a self-hosted runner on hestia, builds a stripped x86_64 binary,
 deposits it at `dl.breadway.dev/<pkg>/<version>/`, updates `index.json`,
 and mirrors the binary to GitHub Releases as a fallback.
@@ -132,6 +132,12 @@ and mirrors the binary to GitHub Releases as a fallback.
 `bakery` always tries `dl.breadway.dev` first and transparently falls back
 to the GitHub Release URL recorded in the manifest.
 
+Beyond stable releases, most products also publish **dev** and **beta**
+tracks — continuous builds off the `dev` and `beta` branches, respectively.
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the branch/release workflow and
+[`docs/release-channels.md`](docs/release-channels.md) for the full track
+policy. Switch tracks with `bakery track set <stable|beta|dev>`.
+
 ### Release artifact contract
 
 Each product's `release.yml` **must** upload the following files alongside

docs/release-channels.md

@@ -54,31 +54,54 @@ should never carry a `bakery.toml` or `PKGBUILD`.
 
 Within the **bakery channel only**, a repo can additionally publish up to
 three **tracks**: `stable` (the existing tag-triggered `v*` flow, unchanged),
-`beta` (a deliberate promotion triggered by a `beta-v*` tag), and `dev`
-(published automatically on every push to the `dev` branch). Don't confuse
-"track" with "channel" above — channel is *how* a binary reaches a user
-(bakery vs. pacman); track is *which build* of a bakery-channel package they
-get.
+`beta` (a frozen stabilization branch), and `dev` (published automatically on
+every push to the `dev` branch). Don't confuse "track" with "channel" above —
+channel is *how* a binary reaches a user (bakery vs. pacman); track is *which
+build* of a bakery-channel package they get.
 
 Each track lives in its own subtree so they never collide:
 
 | Track  | Index URL | Artifact root | Trigger |
 |---|---|---|---|
-| stable | `dl.breadway.dev/index.json` | `/srv/breadway-dl/<pkg>/<ver>/` | push tag `v*` |
-| beta | `dl.breadway.dev/beta/index.json` | `/srv/breadway-dl/beta/<pkg>/<ver>/` | push tag `beta-v*` |
+| stable | `dl.breadway.dev/index.json` | `/srv/breadway-dl/<pkg>/<ver>/` | push tag `v*` on `main` |
+| beta | `dl.breadway.dev/beta/index.json` | `/srv/breadway-dl/beta/<pkg>/<ver>/` | push to branch `beta` |
 | dev | `dl.breadway.dev/dev/index.json` | `/srv/breadway-dl/dev/<pkg>/<ver>/` | push to branch `dev` |
 
 `scripts/gen-index.sh` takes a `TRACK` env var (default `stable`) to select
 which subtree it reads/writes — every existing stable release workflow needs
 zero changes. Dev/beta builds skip the GitHub Release upload step entirely
-(no release-per-commit spam for dev, and beta doesn't need a GitHub mirror
-either) — `dl.breadway.dev` is their only distribution point.
+(no release-per-commit spam, and beta doesn't need a GitHub mirror either) —
+`dl.breadway.dev` is their only distribution point.
+
+**The full branch lifecycle** (see also `CLAUDE.md`'s Branch model section):
+day-to-day work lands on `feature/<name>` or `fix/<issue>` branches, merged
+into `dev`. `dev` publishes a fresh dev-track build on every push — this is
+the "test for a while, fix forward with another push" loop. When `dev` has
+gone roughly a week without new issues, cut `beta` fresh from `dev`'s current
+tip (`git branch -f beta dev` from a clean checkout, then force-push) — this
+freezes it as the stabilization target. `beta` publishes on every push the
+same way `dev` does, but only `fix/<issue>` branches merged directly into
+`beta` should land there afterward; `dev` keeps moving independently for the
+next cycle. After roughly a month of `beta` going without new issues, merge
+`beta` into `main` and push a `vX.Y.Z` tag from `main` to cut the actual
+stable release (the merge itself triggers nothing — tag-push is what fires
+`release.yml`). Reset `beta` fresh from `dev` again to start the next cycle.
+
+Auto-versioning: both `dev` and `beta` compute their build version from the
+latest published `vX.Y.Z` tag (via `git ls-remote --tags`, not `Cargo.toml` —
+`Cargo.toml` can drift stale relative to the actual last release) plus a
+`-dev.<timestamp>+<sha>` / `-beta.<timestamp>+<sha>` suffix. This is
+self-healing regardless of `Cargo.toml` drift and keeps `bakery`'s semver
+check (`is_newer`) meaningful — it will correctly refuse to "update" to a
+build that isn't actually newer than what's installed.
 
 Adding beta/dev to a bakery-channel repo: copy `dev-bakery.yml` /
 `beta-bakery.yml` (or `bread`'s `dev-release.yml` / `beta-release.yml` if the
 repo isn't part of this monorepo) from `bread-ecosystem`/`bread`, and swap
 the repo/binary names the same way the checklist below describes for
-`release.yml`. Not every bakery-channel repo needs beta/dev on day one —
+`release.yml`. Also create the repo's `dev` and `beta` branches if they don't
+exist yet (`git checkout -b dev main` / `git checkout -b beta dev`, push
+both). Not every bakery-channel repo needs beta/dev on day one —
 `gen-index.sh` silently skips any product with no release dir under a given
 track's tree, same as it already does for an unreleased product on stable.