From 9b5031aff2a8c736405aca4a7c05088c8cace25d Mon Sep 17 00:00:00 2001
From: TZGyn <spectator_brethren761@slmails.com>
Date: Sat, 26 Sep 2026 23:05:12 +0800
Subject: [PATCH] Document the upgrade steps and always print them after a
 release
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Readers and future sessions need one obvious place that says how to move
an installed app to the latest version, and the release flow now requires
surfacing those commands in every release report.

💘 Generated with Crush

Assisted-by: Crush:deepseek-v4.1-flash
---
 AGENTS.md | 14 ++++++++++++++
 README.md | 17 +++++++++++++++--
 2 files changed, 29 insertions(+), 2 deletions(-)

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