Gaps fill up, fixes, ui restructuring

docs/runbooks/registry-referrer-troubleshooting.md

@@ -24,8 +24,9 @@ This runbook covers diagnosing and resolving OCI referrer discovery issues durin
 | ECR | Yes | Yes | Requires proper IAM permissions |
 | ACR | Yes | Yes | Full OCI 1.1 support |
 | Harbor 2.0+ | Yes | Yes | Full OCI 1.1 support |
-| Quay | Partial | Yes | Varies by version |
+| Quay | Partial | Yes | Varies by version; admin toggles may control feature |
 | JFrog Artifactory | Partial | Yes | Requires OCI layout repository |
+| GitLab | No | Yes | Stores `subject` field but no referrers endpoint |
 
 See [Registry Compatibility Matrix](../modules/export-center/registry-compatibility.md) for detailed information.
 
@@ -169,6 +170,37 @@ curl "https://registry.example.com/v2/repo/referrers/sha256:abc123?artifactType=
 2. Verify bundle integrity: `sha256sum bundle.tgz`
 3. Check if referrer was intentionally updated upstream
 
+### Issue: Harbor UI shows referrers as "UNKNOWN" artifact type
+
+**Symptoms:**
+- Referrer artifacts (cosign signatures, SBOMs) appear as "UNKNOWN" in Harbor UI
+- API-level discovery works correctly
+
+**Causes:**
+1. Harbor UI mediaType classification lags API capabilities (especially around v2.15+)
+2. Custom artifact types not recognized by Harbor's UI layer
+
+**Solutions:**
+- This is a Harbor-side UI classification issue; it does **not** affect StellaOps referrer discovery or functionality
+- Verify API-level discovery works: `curl -H "Accept: application/vnd.oci.image.index.v1+json" "https://harbor.example.com/v2/repo/referrers/sha256:..."`
+- If needed, check Harbor release notes for mediaType classification updates
+
+### Issue: Quay referrers API returns inconsistent results
+
+**Symptoms:**
+- Referrer discovery works on Quay.io but not on self-hosted Quay
+- Intermittent 404 or empty results from referrers endpoint
+
+**Causes:**
+1. OCI Referrers API feature not enabled in self-hosted Quay deployment
+2. Quay admin toggles or deployment flags controlling the feature
+
+**Solutions:**
+- Verify the OCI Referrers API feature is enabled in Quay's deployment configuration
+- Check Quay admin console for referrers-related feature flags
+- If feature is disabled, StellaOps automatically uses tag-based fallback; no action required
+- Contact Quay administrator to enable the feature if native referrers discovery is preferred
+
 ### Issue: Slow referrer discovery
 
 **Symptoms:**