diff --git a/AGENTS.md b/AGENTS.md
index fa953ea..2bb8be7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -79,6 +79,20 @@ ad-hoc signing (`-`) if none is present. `LSUIElement` is true → no Dock icon.
 Bump `CFBundleShortVersionString`/`CFBundleVersion` via the `build-app.sh`
 version argument and pass the same version to `release.sh`.
 
+## Release process
+
+1. `./release.sh <version>` — builds, zips `SimpleTopBar.app` to
+   `dist/SimpleTopBar.zip`, and prints its sha256 (it does not tag or upload).
+2. Commit and push `main`.
+3. `tea releases create --tag v<version> --asset dist/SimpleTopBar.zip --repo TZGyn/simpletopbar --login gitea.tzgyn.dev`.
+4. Bump `version`/`sha256` in `~/.cache/homebrew-tap/Casks/simpletopbar.rb`,
+   push, then `git -C /opt/homebrew/Library/Taps/tzgyn/homebrew-tap pull --ff-only`.
+
+**Always print the upgrade script after any release or version bump** — the user
+wants it in the final answer every time. Keep it to the cask upgrade commands
+(see the README release section for the exact block), because the app is
+installed through the tap.
+
 ## Gotchas
 
 - `AppListModel` is `@MainActor`; the `NSWorkspace` observers hop back with
diff --git a/README.md b/README.md
index a1be52a..cd5ed7a 100644
--- a/README.md
+++ b/README.md
@@ -44,14 +44,27 @@ brew install --cask simpletopbar
 The tap is hosted on Gitea, so the full URL is required. Homebrew may print an
 "Unsupported tap" warning — it's harmless.
 
+## Upgrade
+
+```bash
+brew update
+brew upgrade --cask simpletopbar
+```
+
+If Gatekeeper still blocks the app after upgrading (it is not notarized yet):
+
+```bash
+xattr -dr com.apple.quarantine /Applications/SimpleTopBar.app
+```
+
 ## Build from source
 
 ```bash
 swift build                 # debug build
 swift run SimpleTopBar      # run from terminal (app appears in the menu bar)
 swift run SimpleTopBar --self-test   # headless check of the dropdown logic
-./build-app.sh 0.1.0        # release build + SimpleTopBar.app bundle + icon + codesign
-./release.sh 0.1.0          # build-app.sh + dist/SimpleTopBar.zip + sha256
+./build-app.sh 0.2.0        # release build + SimpleTopBar.app bundle + icon + codesign
+./release.sh 0.2.0          # build-app.sh + dist/SimpleTopBar.zip + sha256
 ```
 
 ## Around the Background dropdown