diff --git a/.gitea/workflows/scripts/skill-gitea-admin.sh b/.gitea/workflows/scripts/skill-gitea-admin.sh
index 5f28ac3..ab40e24 100644
--- a/.gitea/workflows/scripts/skill-gitea-admin.sh
+++ b/.gitea/workflows/scripts/skill-gitea-admin.sh
@@ -66,6 +66,14 @@ curl -sS -X PUT -H "Authorization: token $AGENT_TOKEN" -H "Content-Type: applica
 Token **scopes** are groups of `read:`/`write:` on: `repository`, `issue`, `organization`, `user`,
 `package`, `notification`, `misc`, and (only for a privileged token) `admin`.
 
+## Token inventory — record everything in `gitea/secrets`
+The private repo **`gitea/secrets`** (readable only by @ffaerber and @ops) is the source of truth for
+tokens. Whenever you mint, rotate, or re-scope a token, append/update a row in its `tokens.md` via the
+contents API (`GET` the file for its `sha`, then `PUT` the updated base64 content with that `sha`):
+`| <token/secret name> | <owner user> | <scopes> | <Actions secret it is stored in> | <notes> |`.
+Storing the live value in the matching Actions secret is what workflows use; the `gitea/secrets` row
+is the human-readable inventory. Never paste a token value into any issue/PR/comment/log.
+
 ## Change a user's token scope (the "update my token" flow)
 Tokens are immutable — you can't edit scopes. Re-mint: delete the old token and create a new one,
 then overwrite the stored secret.