improvements to how scanning works, and helmchart ui

docs/SBOM_SCANNING.md

@@ -202,6 +202,52 @@ SBOM results are stored in two places:
    - Record key: SBOM manifest digest
    - Contains reference to subject image
 
+## Scan Record Status
+
+Every scan attempt produces an `io.atcr.hold.scan` record. The `status` field
+tells the appview how to render the result:
+
+| Status      | Meaning                                                                                          | Stale-loop behavior                              |
+|-------------|--------------------------------------------------------------------------------------------------|--------------------------------------------------|
+| `ok` (or empty) | Scanner produced an SBOM. Vulnerability counts populated; SBOM blob populated.               | Re-scanned on the rescan interval (default 7d).  |
+| `failed`    | Scanner ran but errored (network, OOM, parse failure). No SBOM, no counts.                       | Re-scanned on the rescan interval — failures may be transient. |
+| `skipped`   | Scanner intentionally bypassed the artifact (helm chart, in-toto attestation, DSSE envelope). The `reason` field explains why. | **Never re-queued.** A skipped record won't change without a code change in the scanner. |
+
+Records written before the `status` field existed have an empty status. The
+appview treats empty + nil-blob + zero-count as failed (legacy fallback).
+
+### Unscannable artifact types
+
+The scanner skips artifacts whose config media type appears in
+`unscannableConfigTypes` (`scanner/internal/scan/worker.go`). Currently:
+
+- `application/vnd.cncf.helm.config.v1+json` — Helm charts. Rendered with a
+  helm-aware digest page (`pkg/appview/handlers/digest.go`) that shows
+  Chart.yaml metadata instead of layers / vulns / SBOM.
+- `application/vnd.in-toto+json` — in-toto attestations.
+- `application/vnd.dsse.envelope.v1+json` — DSSE envelopes (SLSA provenance).
+
+For these types the appview's vuln/SBOM tabs render
+*"Vulnerability scanning isn't applied to this artifact type."* — no retry hint.
+
+To add a new unscannable type: append the media type to
+`unscannableConfigTypes`. Existing records won't auto-rewrite — run
+`atcr-hold scan-backfill` once to convert any pre-existing failure records
+into skipped records (see below).
+
+### Backfill tool
+
+`atcr-hold scan-backfill --config <path>` walks every scan record on the
+hold and rewrites legacy ones (empty status + nil blob + zero counts) using
+the manifest's layer media types as a signal:
+
+- Layer media type contains `helm.chart.content`, `in-toto`, or
+  `dsse.envelope` → `status="skipped"`.
+- Otherwise → `status="failed"`.
+
+The tool is idempotent and preserves the original `scannedAt`, so it can be
+re-run safely. Run once per hold after upgrading.
+
 ## Accessing SBOMs
 
 Multiple methods for discovering and retrieving SBOM data.