finish off sprint advisories and sprints

docs/modules/cli/guides/commands/sbom.md

@@ -133,5 +133,95 @@ signed-sbom-{digest}-{timestamp}.tar.gz
 ### Related Commands
 
 - `stella sbom generate` — Generate SBOM from container image
+- `stella sbom publish` — Publish canonical SBOM as OCI referrer
 - `stella attest verify --offline` — Verify attestation bundles offline
 - `stella evidence export` — Export evidence bundle with signed SBOM
+
+---
+
+## stella sbom publish — OCI SBOM Publication
+
+### Synopsis
+
+```bash
+stella sbom publish --image <ref> [--file <path>] [--format cdx|spdx] [--overwrite]
+```
+
+Publishes a canonical (volatile-fields-stripped, key-sorted) SBOM as an OCI referrer artifact attached to the specified container image. The published artifact is discoverable via the OCI Distribution Spec 1.1 referrers API.
+
+### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--image <ref>` | `-i` | **Required.** Target image reference (`registry/repo@sha256:...`). Must include digest. |
+| `--file <path>` | `-f` | Path to SBOM file. If omitted, fetches from Scanner CAS for this image. |
+| `--format <fmt>` | | SBOM format: `cdx` (CycloneDX) or `spdx`. Auto-detected from file content if omitted. |
+| `--overwrite` | | Supersede the current active SBOM referrer for this image. |
+| `--registry-url <url>` | | Override registry URL (defaults to parsed from `--image`). |
+| `--verbose` | | Show detailed output including blob digest and normalization info. |
+
+### Behavior
+
+1. **Normalization**: The SBOM is canonicalized before publication:
+   - Volatile fields stripped: `serialNumber`, `metadata.tools`, `metadata.authors`, `metadata.timestamp` (CycloneDX); `creationInfo.created`, `creationInfo.creators`, `creationInfo.licenseListVersion` (SPDX).
+   - Object keys sorted lexicographically (ordinal).
+   - Arrays of objects sorted by deterministic keys (bom-ref, purl, name@version).
+   - See `docs/contracts/sbom-volatile-fields.json` for the authoritative field list.
+
+2. **Publication**: The canonical SBOM bytes are pushed as an OCI artifact with:
+   - `artifactType`: `application/vnd.stellaops.sbom.cdx+json` or `application/vnd.stellaops.sbom.spdx+json`
+   - `subject`: points to the image manifest digest
+   - Annotations: `dev.stellaops/sbom-version`, `dev.stellaops/sbom-format`
+
+3. **Overwrite/Supersede**: When `--overwrite` is specified:
+   - The current active SBOM referrer is resolved (highest version number).
+   - A new referrer is pushed with `version = prior + 1` and a `dev.stellaops/sbom-supersedes` annotation pointing to the prior manifest digest.
+   - No registry deletes are performed (purely additive).
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Publication succeeded |
+| 1 | Publication failed (registry error, auth failure) |
+| 2 | Error (file not found, invalid image reference, parse error) |
+
+### Examples
+
+```bash
+# Publish a CycloneDX SBOM to an image
+stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file app.cdx.json
+
+# Publish with explicit format
+stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file app.json --format cdx
+
+# Overwrite existing SBOM (supersede)
+stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file improved.cdx.json --overwrite
+
+# Verbose output
+stella sbom publish --image registry.example.com/myapp@sha256:abc123... --file app.cdx.json --verbose
+```
+
+### Sample Output
+
+```
+Published SBOM as OCI referrer:
+  Blob digest:     sha256:e3b0c44298fc1c149afbf4c8996fb924...
+  Manifest digest: sha256:7d865e959b2466918c9863afca942d0f...
+  Version:         1
+  Artifact type:   application/vnd.stellaops.sbom.cdx+json
+```
+
+### Verifier Discovery
+
+Third-party verifiers can discover published SBOMs via the OCI referrers API:
+
+```bash
+# List SBOM referrers for an image (using oras CLI)
+oras discover registry.example.com/myapp@sha256:abc123... \
+  --artifact-type application/vnd.stellaops.sbom.cdx+json
+
+# Pull the latest SBOM
+oras pull registry.example.com/myapp@sha256:abc123... \
+  --artifact-type application/vnd.stellaops.sbom.cdx+json
+```