From 5e3b6b37c88ccb38208f399fd02bdf80fe9d002d Mon Sep 17 00:00:00 2001
From: Behnam Mozafari <behnam.mozafari@thetradedesk.com>
Date: Wed, 13 May 2026 11:09:08 +1000
Subject: [PATCH] docs: clarify <tag> in attestation verify command

Explain that <tag> is the Docker image tag (no v prefix) and document
where to find it. Also collapse the example command onto one line so it
copy-pastes on Windows and macOS shells.

UID2-6764

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 96cd11e..ff2eb4f 100644
--- a/README.md
+++ b/README.md
@@ -47,12 +47,17 @@ Every non-snapshot image published by this repo's release workflow ships with a
 To verify an image, install [`gh`](https://cli.github.com/) (≥ 2.49) and run:
 
 ```bash
-gh attestation verify \
-  oci://ghcr.io/iabtechlab/uid2-optout:<tag> \
-  --owner IABTechLab \
-  --signer-repo IABTechLab/uid2-shared-actions
+gh attestation verify oci://ghcr.io/iabtechlab/uid2-optout:<tag> --owner IABTechLab --signer-repo IABTechLab/uid2-shared-actions
 ```
 
+`<tag>` refers to the **Docker image tag** — bare semantic version, no `v` prefix (e.g. `4.9.64`). Note that the corresponding GitHub release and git tag for the same build are named with a `v` (e.g. `v4.9.64`); the registry tag drops it by OCI convention.
+
+**Where to find a tag:**
+
+- **GitHub Packages** for this repo — [`uid2-optout` package](https://github.com/IABTechLab/uid2-optout/pkgs/container/uid2-optout) lists every published image tag and its digest.
+- Or take a [release](https://github.com/IABTechLab/uid2-optout/releases) name (e.g. `v4.9.64`) and drop the leading `v`.
+- To pin to an exact manifest instead of a mutable tag, use the digest form: `oci://ghcr.io/iabtechlab/uid2-optout@sha256:<digest>` (visible on the Packages page, or via `gh api /orgs/IABTechLab/packages/container/uid2-optout/versions`).
+
 A successful run prints `✓ Verification succeeded!` followed by the SLSA provenance fields — including `sourceRepositoryDigest` (the source commit), `workflow.path` (the signing workflow), and the runner identity.
 
 Snapshot tags (`-SNAPSHOT` suffix) deliberately skip attestation. `gh attestation verify` returns `no attestations found` against a snapshot — that's expected.