[mike@mwxm4]

README.md

@@ -185,6 +185,55 @@ The interactive shell supports the following commands:
 
 ---
 
+## 🔄 Updates
+
+goca updates itself from the releases of the Gitea repository at
+[git.fhi.mpg.de/mike/goca](https://git.fhi.mpg.de/mike/goca):
+
+```bash
+goca --version        # print the running version
+goca --check-update   # only look for a newer release
+goca --update         # download and install the newest release
+```
+
+`--update` fetches the asset `goca-<goos>-<goarch>` of the newest release, runs
+the downloaded binary once with `--version` to make sure it works, and only then
+replaces the running file — following a symlink to the real file behind it.
+
+Besides that, goca looks for a new release **once a day, in the background**: the
+foreground run never touches the network for it, it only reads the note in
+`~/.cache/goca/update.json` (on macOS `~/Library/Caches/goca/update.json`) left
+by the last look and puts a dimmed line on stderr when something newer is out.
+`GOCA_NO_UPDATE_CHECK=1` or the `-y` flag turns that off, and without a terminal
+(pipe, script, cron) goca stays quiet anyway.
+
+### Building and publishing a release
+
+`build.sh` builds every platform into `./bin`, each carrying the same version:
+
+```bash
+./build.sh                        # 1.1.2 -> 1.1.3, all platforms
+PLATFORMS="linux/amd64" ./build.sh   # just one
+VERSION=1.2.0 ./build.sh          # a minor or major step, named outright
+```
+
+`version.txt` holds the version just built and is stepped by 0.0.1 on every run;
+the number goes into the binaries via `-ldflags`, so the literal in `version.go`
+is only what a bare `go build` picks up. The host platform additionally gets the
+symlink `bin/goca`.
+
+For macOS, sign and notarize the two Darwin binaries in place before uploading:
+
+```bash
+./notarize.sh   # needs APPLE_ID, APPLE_PASSWORD, TEAM_ID
+```
+
+Then create a release at git.fhi.mpg.de whose tag is the bare version from
+`version.txt` (e.g. `1.1.3`) and attach the files from `bin/` to it. The asset
+names are what `--update` looks for, so they must stay as `build.sh` writes them.
+
+---
+
 ## 📦 Project Architecture
 
 * [cli.go](file:///Users/mike/src/goca/cli.go) - Command loop, line-completion, history, and user input handler.