Build selected targets with version injection

docs/consumers/build.md

@@ -0,0 +1,62 @@
+# Build versioned application binaries
+
+Use `releasekit.Build` when an application needs binaries for explicit Go
+operating-system and architecture pairs:
+
+```go
+import (
+	"context"
+	"fmt"
+
+	releasekit "gitea.maximumdirect.net/eric/ReleaseKit"
+)
+
+func build(ctx context.Context) error {
+	result, err := releasekit.Build(ctx, releasekit.BuildRequest{
+		RepositoryDir: "/work/project",
+		Version:       "v1.2.3",
+		Spec: releasekit.BuildSpec{
+			MainPackage: "./cmd/project",
+			BinaryName:  "project",
+			Targets: []releasekit.Target{
+				{OS: "linux", Arch: "amd64"},
+				{OS: "linux", Arch: "arm64"},
+				{OS: "darwin", Arch: "arm64"},
+			},
+		},
+		OutputDir: "dist",
+	})
+	if err != nil {
+		return err // result retains completed artifacts when a later step fails.
+	}
+	for _, artifact := range result.Artifacts {
+		fmt.Println(artifact.Filename, artifact.SHA256)
+	}
+	return nil
+}
+```
+
+`Build` records the repository's current `HEAD`, injects the selected stable
+version into `buildinfo.Version`, and returns the compiler identity, normalized
+targets, artifact paths, filenames, and SHA-256 digests. Names follow
+`<binary>-<version>-<goos>-<goarch>`; Windows targets add `.exe`. A repeated
+target pair is built once, at its first position.
+
+The default output directory is `<repository>/dist`; a relative `OutputDir` is
+resolved from the repository. Existing files with a selected artifact name are
+preserved and cause an error. Other files in the output directory are left in
+place. A failed later build or native version check returns the binaries already
+generated in `BuildResult.Artifacts`.
+
+Builds use the prepared local Go toolchain, readonly module mode, disabled
+module network access, `CGO_ENABLED=0`, `-trimpath`, and `-buildvcs=false`. Each
+selected target is compiled explicitly. ReleaseKit then runs the `version`
+command on a native binary and requires `<binary> <version>` followed by a
+newline. If no selected target matches the Go host, it builds a temporary
+native binary for this check and removes it afterward. Cross-compilation does
+not promise that a binary runs on another platform.
+
+An empty target list records the source commit and returns without invoking Go,
+creating the output directory, or running a version check. It does not require a
+main package or binary name. This supports source-only operations without
+silently adding a binary check.

docs/consumers/runtime-version.md

@@ -13,4 +13,5 @@ version := buildinfo.Version()
 Otherwise it returns the executable's main module version when that metadata is
 available and is not `(devel)`. It returns `dev` when neither source provides a
 release identifier. Applications should use this accessor for version output;
-the runtime implementation and ReleaseKit's builder own the injection detail.
+the runtime implementation and [ReleaseKit's build API](build.md) own the
+injection detail.