Expose tagged-source delivery through facade and CLI

docs/consumers/delivery.md

@@ -0,0 +1,81 @@
+# Deliver a tagged source release
+
+Use `releasekit.Deliver` or the `deliver` command after a source tag exists.
+Delivery status is separate from source publication: a delivery problem does
+not move or remove the tag, and a retry can use the same immutable version.
+The operation accepts historical lightweight and annotated tags, including a
+detached checkout, when the checked-out `HEAD` identifies the selected tag
+commit. It does not require the old remote `main` to match.
+
+## Command line
+
+Add a Gitea destination to the profile:
+
+```json
+{
+  "product": "Example",
+  "delivery": {
+    "base_url": "https://gitea.example",
+    "owner": "example",
+    "repository": "example",
+    "token_env": "RELEASEKIT_GITEA_TOKEN"
+  }
+}
+```
+
+Fetch and check out the immutable tag, then deliver it:
+
+```sh
+git checkout --detach v1.2.3
+RELEASEKIT_GITEA_TOKEN="$GITEA_TOKEN" releasekit deliver v1.2.3
+```
+
+The CLI reads the named token variable only for `deliver`; its default name is
+`RELEASEKIT_GITEA_TOKEN`. It verifies the local checkout and hosted tag before
+creating or accepting a hosted release page. The full checked-in note is the
+hosted body. A retry accepts an identical page and matching attachments, adds
+only missing assets, and reports conflicts without replacing content.
+
+With no build targets, delivery is page-only: no builder, version smoke check,
+receipt, binary asset, or checksum manifest is involved. With selected targets,
+the command builds the tagged source into temporary storage and delivers the
+result. To use artifacts built separately, pass `--assets DIR`; the directory
+must contain the private `.releasekit-build.json` receipt created by `build`.
+ReleaseKit checks the receipt's repository, commit, version, resolved build
+settings, and file hashes before making a remote request.
+
+The result reports `complete`, `partial`, `conflict`, `unknown`, or
+`not_attempted`, along with matching, uploaded, pending, conflicting, and
+uncertain assets when known. Exit status 3 means a remote write could not be
+resolved; inspect the same version and retry only after the remote state is
+understood. The command does not run candidate checks or publish tags.
+
+## Go API
+
+Pass the Gitea credential explicitly. A `BuildResult` may be supplied for a
+binary-producing release; it must identify the same tagged repository commit
+and selected version, and its local artifacts must still match their digests.
+Leave `Build` nil for a source-only release.
+
+```go
+result, err := releasekit.Deliver(ctx, releasekit.DeliveryRequest{
+    RepositoryDir: "/work/example",
+    Product:       "Example",
+    Version:       "v1.2.3",
+    Destination: releasekit.GiteaDestination{
+        BaseURL:    "https://gitea.example",
+        Owner:      "example",
+        Repository: "example",
+        Token:      token,
+    },
+})
+if err != nil {
+    // Keep the returned state and any completed asset identities for recovery.
+    return err
+}
+fmt.Println(result.State, result.ReleaseURL)
+```
+
+See the [CLI contract](../cli.md), [configuration reference](../config.md),
+and [Gitea integration guide](../integrations/gitea.md) for exact settings,
+exit codes, and transport behavior.