Track AGENTS.md

State that breadarr is bakery-distributed (not in the BOS ISO, not a GTK
desktop-shell app, no bread events), add CONTRIBUTING.md for the
single-trunk + RC-tag model, ignore leftover src.tar.xz artifacts, and
delete breadarrd/src/src.tar.xz.

.gitignore

@@ -5,7 +5,9 @@ config.toml
 *.db-shm
 
 # Local hygiene notes (not for commit)
-CLAUDE.md
+
+# Leftover source tarballs (never commit these)
+**/src.tar.xz
 
 # graphify knowledge-graph output (local tool cache, not for commit)
 graphify-out/

AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md — Repo hygiene
+
+Scope: this file covers *repo hygiene* — branching, remotes, CI, cleanup. It is not project documentation.
+
+This repo follows the branch/release workflow documented in `CONTRIBUTING.md`
+— read and follow it for any git, branch, or release work here (the
+single-trunk model, `feature/x`/`fix/x` branch naming, how RC tags work,
+etc). Don't improvise a different workflow. The short version: there is one
+long-lived branch, `main` — no `dev` or `beta` branch exists. `main`
+auto-publishes a bakery dev-track build on every push. "Beta" and "stable"
+are both just tags, not branches: push a `vX.Y.Z-rc.N` tag to publish a
+beta-track build, push a plain `vX.Y.Z` tag to cut the signed stable
+release. "Freezing" for stabilization means pausing pushes to `main`, not
+moving a branch.
+
+## Product identity
+
+breadarr is a **homelab** product (single-daemon Sonarr/Radarr/Prowlarr
+replacement: `breadarrd` + `breadarr-tui`). It is bakery-distributed
+(`bakery install breadarr`), **not** baked into the BOS ISO, **not** a
+GTK/desktop-shell app, and does **not** emit or subscribe to bread events.
+bread's `KNOWN_APPS` list already reserves `"arr"`; do not start emitting
+on that id unless an explicit integration pass asks for it.
+
+Do not add a bos-settings panel, a breadway.dev website entry, or an ISO
+bake. Those are out of scope for this product.
+
+## Remotes
+- `origin` — Forgejo (`git.breadway.dev`) only. Unlike most sibling
+  bread-ecosystem repos, this one has no GitHub mirror — don't assume a
+  `github` remote exists. Push `origin` only.
+
+## CI
+
+Workflows live under `.forgejo/workflows/` (not `.github/`):
+
+- `check.yml` — clippy + test on push to `feature/**` and `fix/**`,
+  before a change reaches `main` and triggers a dev-track release.
+- `dev-release.yml` — bakery dev-track build on every push to `main`.
+- `rc-release.yml` — bakery beta-track build on any `vX.Y.Z-rc.N` tag.
+- `release.yml` — signed bakery stable release on any other `v*` tag
+  (skips tags containing `-rc.`).
+
+All four run on the self-hosted `hestia` runner. There is no GitHub
+Release upload (no GitHub mirror). Do not claim this repo has no CI.
+
+## Cleanup
+- Delete feature/fix branches once merged. Check with `git branch --merged main`.
+
+## Don't
+- Don't embed credentials in remote URLs — SSH or a credential helper only.
+- Don't emit bread events, add a settings panel, website entry, or ISO bake.
+- Don't commit leftover source tarballs (`**/src.tar.xz`).

CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing
+
+`breadarr` — single-daemon Sonarr+Radarr+Prowlarr replacement for a
+homelab host (`breadarrd` + `breadarr-tui`).
+
+It is bakery-distributed (`bakery install breadarr`), **not** baked into
+the BOS ISO, **not** a GTK/desktop-shell app, and does **not** emit bread
+events. bread's `KNOWN_APPS` list reserves `"arr"`; this repo does not
+emit on that id.
+
+Part of the bread ecosystem; this repo follows the same single-trunk
+branch/release workflow as every other bakery-channel product.
+
+## Branches
+
+There is one long-lived branch: **`main`**. All day-to-day work lands here.
+Every push to `main` automatically builds and publishes a **dev-track**
+build (see Tracks below) — a real install you can test before cutting
+anything more formal.
+
+New work — features and bug fixes alike — goes on a short-lived branch:
+
+```
+feature/<short-name>
+fix/<issue-number-or-short-name>
+```
+
+Branch off `main`, open a PR/push back into `main` when ready. Short-lived
+branches get deleted on merge — they never accumulate the kind of drift a
+second long-lived branch does.
+
+## The release cycle
+
+There's no separate `beta` or release branch — "stable" and "beta" are both
+just **tags** on `main`, not branches that need to be kept in sync:
+
+1. Work accumulates on `main` 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 fix anything broken with another push.
+2. When you want to stabilize before a real release, tag a release
+   candidate: `git tag vX.Y.Z-rc.1 && git push origin vX.Y.Z-rc.1`. That
+   tag alone triggers a beta-track build — "freezing" is just pausing
+   pushes to `main` while you test it, not a branch operation. Cut
+   `-rc.2`, `-rc.3`, etc. for further fixes.
+3. Once an RC has gone without issues, tag the real release:
+   `git tag vX.Y.Z && git push origin vX.Y.Z` — that's what triggers the
+   signed stable release build.
+
+This repo has no GitHub mirror. Push tags and branches to `origin`
+(Forgejo) only.
+
+## 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 | a `vX.Y.Z` tag |
+| `beta` | Latest release candidate | a `vX.Y.Z-rc.N` tag |
+| `dev` | Bleeding edge | `main`, on every push |
+
+Dev versions are auto-computed (`X.Y.Z-dev.<timestamp>+<sha>`) from the
+latest published stable tag, so they always sort as newer than what you
+have installed — no manual version bumping needed. Beta versions are just
+the RC tag itself (already valid semver, already sorts below the real
+release it's a candidate for).
+
+## Local development
+
+```sh
+cargo build --release --workspace --locked
+cargo test --workspace --locked
+cargo clippy --workspace --all-targets --locked -- -D warnings
+```
+
+Host tools the daemon shells out to: `mkvtoolnix-cli` (`mkvmerge`) and
+`ffmpeg`/`ffprobe`. See `bakery.toml` and the README setup section.
+
+## CI
+
+- `check.yml` — clippy + test on push to `feature/**` and `fix/**`.
+- `dev-release.yml` — triggered on push to `main`.
+- `rc-release.yml` — triggered on any `vX.Y.Z-rc.N` tag push.
+- `release.yml` — triggered on any other `v*` tag push, cuts the actual
+  stable release.
+
+All CI runs on a self-hosted runner. See
+[bread-ecosystem's docs/release-channels.md](https://git.breadway.dev/Breadway/bread-ecosystem/src/branch/main/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.

README.md

@@ -5,6 +5,10 @@ A single-daemon Rust replacement for the Sonarr + Radarr + Prowlarr stack — on
 - **`breadarrd`** — the daemon. Watches sources, matches releases to your library, scores and grabs candidates, imports completed downloads, probes them for real ground-truth quality, and refreshes Jellyfin. Runs as a `systemd --user` service.
 - **`breadarr-tui`** — a terminal client (ratatui) that talks to `breadarrd`'s local HTTP API. No web UI, on purpose.
 
+## Distribution
+
+breadarr is a **homelab** product. It is distributed through bakery (`bakery install breadarr`) and is **not** baked into the BOS ISO. It is not a GTK/desktop-shell app, has no bos-settings panel, and does not subscribe to or emit bread events. bread's `KNOWN_APPS` list reserves the `"arr"` app id for a possible future integration; this repo does not emit on that id.
+
 ## Why this exists
 
 Sonarr + Radarr + Prowlarr is three separate services, three databases, three web UIs, and a lot of setup surface for one workflow: watch for releases, pick the best one, download it, file it correctly, tell Jellyfin. breadarr collapses that into a single daemon, with a few specific problems solved directly rather than configured around:
@@ -29,6 +33,8 @@ All three search-driven sources share one per-cycle request budget (default: 5 s
 
 ## Setup
 
+Install via bakery (`bakery install breadarr`) on a homelab host, or build from this repo. breadarr is not on the BOS ISO.
+
 1. Copy `config.example.toml` to `~/.config/breadarr/breadarrd.toml` and fill in:
    - qBittorrent WebUI URL/credentials
    - Jellyfin URL + API key