docs: document the --update-product flag for snapshot inventory reconciliation (#29)

Adds --update-product to the publish Snapshots flag reference in
ARGUMENTS.md and a "Reconciling a Product's Inventory to a Snapshot"
section in README.md. The flag reconciles a product's inventory to a
snapshot (removing snapshot-labeled assets that predate the timestamp)
then adds the published asset. Requires --product-id and both snapshot
flags; mutually exclusive with --replace-in-product.

Author: lsell-manifest

ARGUMENTS.md

@@ -161,8 +161,9 @@ Publish SBOM(s) to the Manifest platform.
 |------|-------|------|---------|-------------|
 | `--snapshot-label` | - | string | - | Label identifying the snapshot this SBOM belongs to, e.g. an environment name or release tag (required with `--snapshot-timestamp`) |
 | `--snapshot-timestamp` | - | string | - | RFC3339 timestamp the snapshot represents, with an explicit UTC offset, e.g. `2024-01-15T10:00:00Z` (required with `--snapshot-label`) |
+| `--update-product` | - | bool | `false` | After upload, reconcile the product's inventory to the snapshot (remove assets carrying the snapshot label that predate the timestamp), then add this asset. Requires `--product-id`, `--snapshot-label`, and `--snapshot-timestamp`; mutually exclusive with `--replace-in-product` |
 
-> **Note:** Pass both flags together to enable snapshot mode. The timestamp must be RFC3339 with a UTC offset, must not be in the future, and must not be more than 7 days in the past. See [Publishing Snapshots](README.md#publishing-snapshots) in the README for what snapshot mode does.
+> **Note:** Pass both snapshot flags together to enable snapshot mode. The timestamp must be RFC3339 with a UTC offset, must not be in the future, and must not be more than 7 days in the past. Add `--update-product` (with `--product-id`) to also reconcile a product's inventory to the snapshot. See [Publishing Snapshots](README.md#publishing-snapshots) in the README for what snapshot mode does.
 
 ### VDR (Vulnerability Disclosure Report)
 

README.md

@@ -429,6 +429,26 @@ manifest-cli publish sbom.json \
 
 > **Note:** The deactivation sweep only runs when snapshot mode is enabled. Snapshot mode and `--deactivate-older` serve different purposes: `--deactivate-older` deactivates prior versions of the same asset, while snapshots reconcile an entire environment or release against a point in time.
 
+### Reconciling a Product's Inventory to a Snapshot
+
+While snapshot mode reconciles your organization's asset inventory, `--update-product` reconciles a specific **product's inventory** to the same snapshot. After the upload completes, it removes assets in the product that carry the snapshot label and predate the snapshot timestamp, then adds the asset you are publishing. This keeps a product's inventory in sync with exactly what a given environment or release contains.
+
+`--update-product` requires `--product-id`, `--snapshot-label`, and `--snapshot-timestamp`, and is mutually exclusive with `--replace-in-product` (use `--replace-in-product` for a single per-asset version swap, and `--update-product` for a full snapshot reconciliation).
+
+The reconcile is idempotent across a batch: when you publish several SBOMs to the same product and snapshot, only the first call removes stale assets, and each subsequent call just adds its asset. This makes it safe to loop over every service in a deploy:
+
+```bash
+export MANIFEST_API_KEY=your-api-token
+SNAPSHOT_TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+for sbom in service-a.json service-b.json service-c.json; do
+  manifest-cli publish "$sbom" \
+    --product-id YOUR_PRODUCT_ID \
+    --update-product \
+    --snapshot-label production \
+    --snapshot-timestamp "$SNAPSHOT_TS"
+done
+```
+
 ## (Beta) Generating & Publishing SBOM Attestation
 
 ## Keyless Signing