Document producer upload client behavior

docs/operations.md

@@ -148,6 +148,25 @@ curl -X POST http://127.0.0.1:8080/upload \
   --data-binary @bundle.tar.gz
 ```
 
+Go producer applications can use `pkg/upload` instead of constructing archives and HTTP requests directly. The package sends `Idempotency-Key` on every upload, derives `/upload` from the configured endpoint, and reuses the same key and replayable request body for safe retries:
+
+```go
+client, err := upload.NewClient(upload.ClientOptions{
+	Endpoint: "http://127.0.0.1:8080",
+	Token:    token,
+})
+result, err := client.UploadBundle(ctx, upload.UploadBundleOptions{
+	Root:           "examples/source-bundle",
+	IdempotencyKey: "producer.run.20260604T120000Z",
+})
+```
+
+The maintained example client uses the local upload server and reads the token from `DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN`. It generates an idempotency key by default; set `DISTRIBUTOR_EXAMPLE_UPLOAD_IDEMPOTENCY_KEY` when a retry must be stable across separate process runs.
+
+```sh
+go run ./examples/upload-client
+```
+
 Accepted uploads return after the archive is staged and validated:
 
 ```json