diff --git a/CLAUDE.md b/CLAUDE.md
index 20d1900..17810c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,17 +2,16 @@
 
 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; 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.
+This repo follows the branch/release workflow documented in `CONTRIBUTING.md`
+— read and follow it for any git, branch, or release work here (the
+dev/beta/main lifecycle, `feature/x`/`fix/x` branch naming, when to cut or
+reset `beta`, etc). Don't improvise a different workflow. The short version:
+`main` is tag-ready and only moves via a `beta` merge; `dev` and `beta` both
+auto-publish a build on every push (dev-track / beta-track respectively);
+`beta` is a frozen stabilization branch cut from `dev` roughly weekly and
+promoted to `main` roughly monthly. `git branch -f beta dev` (plain
+branch-pointer move) is how `beta` gets reset — never `git checkout
+main`/`git merge` for this.
 
 ## Remotes
 - `origin` — Forgejo (`git.breadway.dev` via Hestia, SSH) — authoritative.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6087898
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,95 @@
+# Contributing
+
+This repo hosts `bakery` (the ecosystem package manager) and `bread-theme`
+(the shared theming crate). Other ecosystem products (`bread`, `breadbar`,
+`breadbox`, …) live in their own repos under `Breadway/` but follow the same
+workflow described here.
+
+## Branches
+
+- **`main`** — release branch, always tag-ready. Nothing is committed to it
+  directly; it only moves forward via a `beta` merge (see below).
+- **`dev`** — integration branch. All day-to-day work lands here first.
+  Every push to `dev` automatically builds and publishes a **dev-track**
+  build (see Tracks below) — use this to test your change in a real install
+  before it goes any further.
+- **`beta`** — a frozen stabilization branch, cut from `dev` periodically.
+  Every push to `beta` automatically builds and publishes a **beta-track**
+  build. While a freeze is active, only fixes for issues found *in that
+  freeze* should land on `beta`.
+
+New work — features and bug fixes alike — goes on a short-lived branch:
+
+```
+feature/<short-name>
+fix/<issue-number-or-short-name>
+```
+
+Branch off `dev`, open a PR/push back into `dev` when ready. If you're fixing
+something reported against an active `beta` freeze, branch off `beta`
+instead, merge the fix there to unblock testers, and also forward the same
+fix into `dev` so it doesn't quietly reappear next cycle.
+
+## The release cycle
+
+1. Work accumulates on `dev` via `feature/x` / `fix/x` branches. Each push
+   auto-publishes a dev build — install it with `bakery track set dev` and
+   `bakery update --all`, then report or fix anything broken with another
+   push to `dev`.
+2. Once `dev` has gone roughly **a week** without new issues, `beta` is cut
+   fresh from `dev`'s current tip. This freezes it as the stabilization
+   target — `dev` keeps moving independently starting the next cycle.
+3. `beta` is open for anyone to test: `bakery track set beta` and
+   `bakery update --all`. **File issues against anything you find on this
+   repo's Forgejo issue tracker.** Fixes land via `fix/<issue>` branches
+   merged into `beta`.
+4. Once `beta` has gone roughly **a month** without new issues, it's merged
+   into `main` and tagged `vX.Y.Z` — that tag is what actually triggers the
+   stable release build. `beta` is then reset from `dev` to start the next
+   cycle.
+
+## Tracks, from a user's perspective
+
+```
+bakery track show              # what you're currently on (defaults to stable)
+bakery track set dev           # or beta, or stable
+bakery update --all            # pull the latest build on your current track
+```
+
+| Track  | What it is | Published from |
+|--------|-----------|-----------------|
+| `stable` | The last tagged release | `main`, on a `vX.Y.Z` tag push |
+| `beta` | Current stabilization freeze | `beta`, on every push |
+| `dev` | Bleeding edge | `dev`, on every push |
+
+Dev/beta versions are auto-computed (`X.Y.Z-dev.<timestamp>+<sha>` /
+`-beta.…`) from the latest published stable tag, so they always sort as
+newer than what you have installed — no manual version bumping needed when
+pushing to `dev` or `beta`.
+
+## Local development
+
+```sh
+cargo build --release -p bakery
+cargo test --release -p bakery
+```
+
+Both `bakery` and `bread-theme` are members of this workspace's Cargo.toml.
+Run the same commands with `-p bread-theme --bin bread-theme` for that crate.
+
+## CI
+
+- `dev-bakery.yml` / `dev-bread-theme.yml` — triggered on push to `dev`.
+- `beta-bakery.yml` / `beta-bread-theme.yml` — triggered on push to `beta`.
+- `release-bakery.yml` / `release-bread-theme.yml` — triggered on a `v*` tag
+  push, cuts the actual stable release.
+- `package.yml` — publishes to the `[breadway]` pacman repo, also tag-triggered.
+
+All CI runs on a self-hosted runner; nothing runs automatically on plain
+commits or PRs beyond the track builds above. See
+[`docs/release-channels.md`](docs/release-channels.md) for the full policy,
+including how a new product gets wired onto these tracks.
+
+## Questions
+
+Open an issue on this repo's Forgejo tracker.
diff --git a/docs/release-channels.md b/docs/release-channels.md
index aa71900..019ecf3 100644
--- a/docs/release-channels.md
+++ b/docs/release-channels.md
@@ -147,9 +147,8 @@ missing it; that gap is intentional and about to be moot everywhere.
 |---|---|---|---|---|
 | bread-ecosystem (bakery product) | yes | yes | stable, beta, dev | `release-bakery.yml` recovered from a dead `.github/workflows/release.yml` that referenced a `hestia` self-hosted runner GitHub never had registered |
 | bread-ecosystem (bread-theme product) | yes | no | stable, beta, dev | |
-| bread | yes | yes | stable, beta, dev | pilot repo for the beta/dev track rollout |
-| breadbar, breadbox, breadcrumbs, breadpad, breadpaper | yes | yes | stable only | complete, used as templates; not yet rolled out to beta/dev |
-| breadclip, breadmon, breadsearch, breadshot | yes | no | stable only | complete |
+| bread, breadbar, breadbox, breadcrumbs, breadpad, breadpaper | yes | yes | stable, beta, dev | complete on all three tracks |
+| breadclip, breadmon, breadsearch, breadshot | yes | no | stable, beta, dev | complete on all three tracks |
 | breadlock, breadhelp | no | yes | n/a | breadlock's `bakery.toml` was removed as orphaned; its README wrongly claimed it was a registry entry |
 | bos-settings | yes | yes | stable only | was missing both the registry entry and `release.yml`; both added |
 | bos | no | no | n/a | ISO-only via `release-iso.yml`; had an erroneous `bakery.toml` copy-pasted from bos-settings, removed |