Make product checks additive

docs/consumers/build.md

@@ -70,9 +70,9 @@ silently adding a binary check.
 
 The [`build` command](../cli.md) reads the same build specification from the
 profile and writes a private receipt alongside its artifacts. `check` and
-`publish` run selected builds after their one validation callback using
-temporary output outside the worktree; those candidate checks do not write a
-receipt or leave build files in the repository.
+`publish` run selected builds after the standard suite and any additional
+checks using temporary output outside the worktree. Candidate checks do not
+write a receipt or leave build files in the repository.
 
 For delivery from a tagged checkout, `deliver` builds selected tagged-source
 targets into temporary storage by default. Use `--assets DIR` to deliver a

docs/consumers/check.md

@@ -8,7 +8,7 @@ result, err := releasekit.Check(ctx, releasekit.ReleaseRequest{
 	RepositoryDir: "/work/project",
 	Product:       "Example",
 	Version:       "v1.2.3",
-	Validate: func(ctx context.Context, candidate releasekit.Candidate) error {
+	AdditionalChecks: func(ctx context.Context, candidate releasekit.Candidate) error {
 		return runProjectChecks(ctx, candidate.RepositoryDir)
 	},
 })
@@ -24,10 +24,9 @@ version must be stable `vMAJOR.MINOR.PATCH`. The committed
 product name and exact version as complete title elements. No local tag with
 that version may already exist.
 
-The callback receives the captured repository, commit, and version. ReleaseKit
-calls it once. When omitted, ReleaseKit runs
-`go test -mod=readonly -count=1 ./...` with the available compatible local Go
-toolchain; it does not download a different toolchain automatically. The suite
+ReleaseKit always runs `go test -mod=readonly -count=1 ./...` with the available
+compatible local Go toolchain, then calls `AdditionalChecks` once when supplied.
+It does not download a different toolchain automatically. The standard suite
 uses the Go host target, disables workspace and module network access, and
 ignores ambient `GOFLAGS`, experiment, and CPU feature overrides. Effective
 cache and native cgo/C-tool settings are preserved, including values from Go's
@@ -36,18 +35,20 @@ cleanliness after validation.
 
 A successful check is evidence about the local candidate only. It does not
 check whether a remote branch or tag is available and does not create a tag.
-The [`check` command](../cli.md) reads the product and optional validation
+The [`check` command](../cli.md) reads the product and optional additional
 commands from `releasekit.json`.
 
 ## Publishing the source tag
 
-`releasekit.Publish` uses the same request and performs candidate validation,
+`releasekit.Publish` uses the same request and validation order: the standard
+suite runs first, followed by `AdditionalChecks` when supplied. It then performs
 authoritative remote checks, annotated-tag creation, and an exact tag push. The
 selected remote must publish `main` at the captured commit and must not already
 contain the selected version tag. A successful result includes the endpoint and
 tag object ID. Publication states distinguish an unattempted push, a tag that
 was created locally but not pushed, a successful push, a guard conflict, and an
-unresolved push error.
+unresolved push error. See the [publication guide](publish.md) for the complete
+workflow.
 
 When a push reports an error, ReleaseKit makes one bounded query for the
 authoritative tag. An exact tag object match confirms success. An absent tag is

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.