Make product checks additive

docs/consumers/publish.md

@@ -0,0 +1,41 @@
+# Source tag publication
+
+Use `releasekit.Publish` to validate a committed candidate and push its exact
+annotated source tag:
+
+```go
+result, err := releasekit.Publish(ctx, releasekit.ReleaseRequest{
+	RepositoryDir: "/work/project",
+	Product:       "Example",
+	Version:       "v1.2.3",
+	AdditionalChecks: func(ctx context.Context, candidate releasekit.Candidate) error {
+		return runProjectChecks(ctx, candidate.RepositoryDir)
+	},
+})
+if err != nil {
+	return err
+}
+fmt.Println(result.Version, result.CandidateCommit, result.TagObject)
+```
+
+Publication captures a clean candidate on `main`, validates its committed
+release note, and checks the selected remote before running candidate checks.
+It always runs `go test -mod=readonly -count=1 ./...` with the available
+compatible local Go toolchain. It then calls `AdditionalChecks` once when
+supplied. The standard suite cannot be replaced; move product-specific behavior
+into `AdditionalChecks` and remove repeated standard-suite commands from custom
+checks. A failed suite or additional check prevents tag creation, and wrapped
+errors preserve their causes.
+
+If `Build` selects targets, ReleaseKit verifies them after the standard suite
+and additional checks, before creating the tag. The operation then rechecks the
+candidate and remote guards, creates an annotated tag for the captured commit,
+and pushes only that tag object.
+
+A successful result means Git confirmed the push or an exact authoritative tag
+query confirmed it after a push error. The local tag is retained after a failed
+push. `PublicationState` distinguishes a known failure, conflict, confirmed
+publication, and unresolved outcome. Resolve an unknown result against the
+captured endpoint before retrying; see the [maintainer procedure](../release.md)
+for the recovery steps. The [CLI contract](../cli.md) documents command output
+and exit statuses.