test fixes and new product advisories work

docs/modules/airgap/guides/offline-bundle-format.md

@@ -191,6 +191,85 @@ stellaops alert bundle verify --file ./bundles/alert-123.stella.bundle.tgz
 stellaops alert bundle import --file ./bundles/alert-123.stella.bundle.tgz
 ```
 
+## OCI Referrer Artifacts
+
+Mirror bundles automatically include OCI referrer artifacts (SBOMs, attestations, signatures) discovered from container registries. These artifacts are stored under a dedicated `referrers/` directory keyed by subject image digest.
+
+### Referrer Directory Structure
+
+```
+bundle.stella.bundle.tgz
+├── ...existing structure...
+├── referrers/
+│   └── sha256-abc123.../                # Subject image digest
+│       ├── sha256-def456.json           # CycloneDX SBOM
+│       ├── sha256-ghi789.json           # in-toto attestation
+│       └── sha256-jkl012.json           # VEX statement
+└── indexes/
+    ├── referrers.index.json             # Referrer artifact index
+    └── attestations.index.json          # Attestation cross-reference
+```
+
+### Manifest Referrers Section
+
+The bundle manifest includes a `referrers` section documenting all discovered artifacts:
+
+```yaml
+referrers:
+  subjects:
+    - subject: "sha256:abc123..."
+      artifacts:
+        - digest: "sha256:def456..."
+          artifactType: "application/vnd.cyclonedx+json"
+          mediaType: "application/vnd.oci.image.manifest.v1+json"
+          size: 12345
+          path: "referrers/sha256-abc123.../sha256-def456.json"
+          sha256: "def456789..."
+          category: "sbom"
+          annotations:
+            org.opencontainers.image.created: "2026-01-27T10:00:00Z"
+        - digest: "sha256:ghi789..."
+          artifactType: "application/vnd.in-toto+json"
+          mediaType: "application/vnd.oci.image.manifest.v1+json"
+          size: 8192
+          path: "referrers/sha256-abc123.../sha256-ghi789.json"
+          sha256: "ghi789abc..."
+          category: "attestation"
+```
+
+### Referrer Validation
+
+The `ImportValidator` verifies referrer artifacts during bundle import:
+
+| Validation | Severity | Description |
+|------------|----------|-------------|
+| `ReferrerMissing` | Error | Declared artifact not found in bundle |
+| `ReferrerChecksumMismatch` | Error | SHA-256 doesn't match declared value |
+| `ReferrerSizeMismatch` | Error | Size doesn't match declared value |
+| `OrphanedReferrer` | Warning | File exists in `referrers/` but not declared |
+
+### Artifact Types
+
+| Artifact Type | Category | Description |
+|---------------|----------|-------------|
+| `application/vnd.cyclonedx+json` | `sbom` | CycloneDX SBOM |
+| `application/vnd.spdx+json` | `sbom` | SPDX SBOM |
+| `application/vnd.openvex+json` | `vex` | OpenVEX statement |
+| `application/vnd.csaf+json` | `vex` | CSAF advisory |
+| `application/vnd.in-toto+json` | `attestation` | in-toto attestation |
+| `application/vnd.dsse.envelope+json` | `attestation` | DSSE envelope |
+| `application/vnd.slsa.provenance+json` | `attestation` | SLSA provenance |
+| `application/vnd.stella.rva+json` | `attestation` | RVA attestation |
+
+### Registry Compatibility
+
+Referrer discovery supports both OCI 1.1 native API and fallback tag-based discovery:
+
+- **OCI 1.1+**: Uses native `/v2/{repo}/referrers/{digest}` endpoint
+- **OCI 1.0 (fallback)**: Discovers via `sha256-{digest}.*` tag pattern
+
+See [Registry Compatibility Matrix](../../export-center/registry-compatibility.md) for per-registry details.
+
 ## Function Map Artifacts
 
 Bundles can include runtime linkage verification artifacts. These are stored in dedicated subdirectories: