docs: explain tags vs digests across security and registry pages (#1617)

docs/features/vulnerability-scanning.mdx

@@ -63,7 +63,7 @@ Hovering a badge reveals the breakdown by severity and the scan timestamp. The b
 | **LOW** (muted) | Only low-severity vulnerabilities |
 | **Clean** (green) | Scan completed with zero findings |
 
-Scan results are cached by image digest. If the same digest is scanned again within 24 hours, Sencho returns the cached result instantly instead of re-running Trivy. To force a fresh scan, open the drawer and click **Re-scan**.
+Scan results are cached by image digest (see [Tags vs digests](#tags-vs-digests)). If the same digest is scanned again within 24 hours, Sencho returns the cached result instantly instead of re-running Trivy. To force a fresh scan, open the drawer and click **Re-scan**.
 
 ## The scan results drawer
 
@@ -345,6 +345,25 @@ Typical upload flow for GitHub code scanning:
     sarif_file: sencho-scan.sarif.json
 ```
 
+
+## Tags vs digests
+
+A **tag** is a mutable name for an image (`nginx:1.25`, `app:latest`). Compose files and day-to-day updates usually pin by tag because the name is easy to read and bump.
+
+A **digest** is the immutable content hash of that image (`sha256:…`, often written as `image@sha256:…`). The registry can move a tag to a new digest without changing the tag name, so two pulls of `app:latest` can be different builds.
+
+Sencho keys security work on digest when Docker provides one:
+
+- The 24-hour scan cache
+- History primary labels and per-identity retention
+- Apples-to-apples scan comparison
+
+When no digest is stored (for example a compose config scan), History falls back to the image reference.
+
+Tags still drive operations: compose pins, Resources row labels, semver auto-update, and the admin **Registry tags** browser (remote tag names only; see [Private registries](/features/private-registries#browse-tags-from-resources)).
+
+When the tag name is unchanged but the remote content changed, auto-update surfaces **Rebuild available** / **Digest rebuild**, and a new scan gets its own History row under the new digest. Comparing across digests is allowed but flagged. If compose declares a tag while the running container is digest-pinned, [Stack drift](/features/stack-drift#image-comparison) treats them as different references on purpose.
+
 ## Scan history
 
 Every scan Sencho runs is stored with its full vulnerability detail. History retention keeps a configurable number of scans per image digest (or per image reference when no digest is stored; default 50). Configure the cap under **Settings → Operations → Data Retention**. The history powers two things: digest caching (skip re-scanning a digest already scanned within 24 hours) and trend insight (compare a new scan to its predecessor to see what changed).