From e8baf91e918a8c35c2351bd1b03c1a15235ff898 Mon Sep 17 00:00:00 2001
From: Viet Anh Nguyen <vietanh.dev@gmail.com>
Date: Mon, 20 Jul 2026 10:41:26 +0700
Subject: [PATCH] docs(apt): signing key is configured; show the verified path

A GPG signing key is now set as APT_GPG_PRIVATE_KEY / APT_GPG_PASSPHRASE,
so the next tagged release publishes a signed repository and the generated
index page switches to signed-by=.

The published repository is still unsigned until that release happens, so
[trusted=yes] stays the working instruction and is still labelled as
skipping verification. The signed commands sit below it, marked as taking
effect from the next release, rather than replacing instructions that do
not work yet.

Verified end to end before writing this: the release step's shell was
extracted from the merged workflow and run against the real key, and the
resulting InRelease and Release.gpg verify against the published public
key alone -- which is what a user's apt actually does.
---
 docs/download.md | 49 +++++++++++++++++++++++++++++++++++-------------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/docs/download.md b/docs/download.md
index 08804c9..8acafe2 100644
--- a/docs/download.md
+++ b/docs/download.md
@@ -121,21 +121,44 @@ sudo apt install thinkutils
 ```
 
 ::: warning What `[trusted=yes]` means
-This repository is not yet GPG-signed, and `[trusted=yes]` tells `apt` to install
-from it without verifying any signature. HTTPS still authenticates the server for
-the duration of the download, but nothing proves the packages are the ones our CI
-built — and ThinkUtils installs a helper that runs as root.
-
-If that trade-off is not one you want to make, download the `.deb` from the
-[releases page](https://github.com/vietanhdev/ThinkUtils/releases) and install it
-with `apt install ./thinkutils_*.deb` instead. You give up automatic updates and
-check for new versions yourself.
-
-Signing is implemented and waiting on a key — see
-[apt-signing](/development/apt-signing). Once it is enabled these instructions
-change to `signed-by=` and the `[trusted=yes]` flag goes away.
+`[trusted=yes]` tells `apt` to install without verifying any signature. HTTPS
+still authenticates the server for the duration of the download, but nothing
+proves the packages are the ones our CI built — and ThinkUtils installs a helper
+that runs as root.
+
+It is needed because the **currently published** repository is unsigned. A
+signing key is now configured, so the next release will publish a signed
+repository and these instructions change to the ones below.
+
+If you would rather not take that trade in the meantime, download the `.deb`
+from the [releases page](https://github.com/vietanhdev/ThinkUtils/releases) and
+install it with `apt install ./thinkutils_*.deb`. You give up automatic updates
+and check for new versions yourself.
 :::
 
+### From the next release: verified installs
+
+Once a signed release is published, `https://gh.vietanh.dev/ThinkUtils/apt` will
+carry `InRelease`, `Release.gpg`, and the public key. Switch to:
+
+```bash
+curl -fsSL https://gh.vietanh.dev/ThinkUtils/apt/thinkutils-archive-keyring.asc \
+  | sudo gpg --dearmor -o /usr/share/keyrings/thinkutils-archive-keyring.gpg
+
+echo "deb [signed-by=/usr/share/keyrings/thinkutils-archive-keyring.gpg] https://gh.vietanh.dev/ThinkUtils/apt ./" \
+  | sudo tee /etc/apt/sources.list.d/thinkutils.list
+
+sudo apt update
+sudo apt install thinkutils
+```
+
+`signed-by=` scopes the key to this one repository, so it cannot vouch for
+packages from anywhere else in your sources. The repository's own index page
+always shows whichever form is currently published — it is generated from what
+the release actually produced, so it cannot disagree with reality.
+
+Maintainers: see [apt-signing](/development/apt-signing).
+
 ## Before fan control works
 
 One step is not optional, and it is the most common reason people think the app