From 6c7771e04cb6d5aabda8893fcd915ee5f44f2f5c Mon Sep 17 00:00:00 2001
From: tiennm99 <tiennm99@outlook.com>
Date: Wed, 21 Oct 2026 17:06:21 +0700
Subject: [PATCH] docs: describe the release assets, their name contract and
 the residual update risk

---
 docs/release-process.md | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/docs/release-process.md b/docs/release-process.md
index 0b706e0..9324563 100644
--- a/docs/release-process.md
+++ b/docs/release-process.md
@@ -19,8 +19,14 @@ below matters: bump Cargo *before* you tag.
    ```
 
 5. Watch the "Release" workflow run; it creates the GitHub Release
-   with `claude-code-usage-bubble.exe` attached and auto-generated
-   notes.
+   with auto-generated notes and these assets:
+   `claude-code-usage-bubble.exe` and its `.sig`,
+   `claude-code-usage-bubble_X.Y.Z_amd64.AppImage` and its `.sig`,
+   `claude-code-usage-bubble_X.Y.Z_amd64.deb`, and `latest.json`.
+   The build jobs need the `TAURI_SIGNING_PRIVATE_KEY` and
+   `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` secrets and a non-empty
+   `plugins.updater.pubkey` in `tauri.conf.json`; the workflow fails
+   before building without them.
 
 ## Testing without a real tag
 
@@ -28,6 +34,9 @@ Use the workflow's `workflow_dispatch` input with a throwaway tag
 like `v0.0.0-test`. The release is created as a **draft**, so it
 does not show up on the public Releases feed or trigger self-updates
 for users.
+The tag must already exist and point at a commit whose `Cargo.toml`
+version matches it (`0.0.0-test` here), because the version check also
+runs for drafts. Delete the draft and the tag after inspecting it.
 
 ## Versioning
 
@@ -38,8 +47,26 @@ so a higher tuple wins.
 
 ## Asset name contract
 
-The updater matches the release asset by exact filename
-`claude-code-usage-bubble.exe` (case-insensitive). Cargo's
-`name = "claude-code-usage-bubble"` already produces that name in
-`target/release/`, so the workflow uploads the file as-is — do not
-rename it.
+Legacy clients (v0.5.0 and earlier) read `/releases/latest` through
+the GitHub API and download the asset named
+`claude-code-usage-bubble.exe` (case-insensitive), else the first asset
+ending in `.exe`. The release must therefore carry exactly one `.exe`
+asset, under that name, uploaded unmodified so the GitHub `digest`
+they verify matches. Tauri clients read `latest.json`, whose URLs must
+match the asset names exactly, so the Linux bundles are renamed to
+space-free names before upload. `scripts/make-latest-json.js` enforces
+both rules and fails the release otherwise.
+
+## Residual risk
+
+The hand-over from a legacy Win32 release to the Tauri exe has been
+checked only by reading the updater code at v0.4.0, v0.4.1 and v0.5.0;
+it has never run end to end before a release. Static reading cannot
+prove runtime behaviour such as antivirus or SmartScreen reactions to
+a self-replaced, larger, unsigned exe, WebView2 start-up from a
+detached relaunch, or the v0.4.0 helper timing. The first Tauri
+release is the first real run. Mitigations: the WebView2 guard, the
+`--diagnose` log, `update-error.log`, and the `release-legacy.yml`
+rollback, which rebuilds the Win32 sources at a given ref under a
+higher version as a Windows-only release. That rollback is itself
+unproven end to end.