Document versioned Go tool adoption for CLI consumers

README.md

@@ -8,8 +8,9 @@ tagged-source delivery API, and the `version`, `check`, `publish`, `build`,
 maintainer procedure and prepared Woodpecker workflow for hosted note-page
 delivery are documented. ReleaseKit does not declare binary deliverables.
 
-See the [v0.1.0 release note](docs/releases/v0.1.0.md) for the initial baseline
-and installation commands.
+See the [consumer adoption guide](docs/consumers/adoption.md) to add ReleaseKit
+as a versioned Go tool or package dependency, and the
+[v0.1.0 release note](docs/releases/v0.1.0.md) for the initial baseline.
 
 Run the offline Go test suite from the repository root with:
 
@@ -42,6 +43,8 @@ failure recovery.
 
 ## Documentation
 
+- [Consumer adoption](docs/consumers/adoption.md): versioned CLI tool and Go API
+  dependencies, upgrades, and CI adoption.
 - [Contributor guide](docs/development.md): orientation, validation, and selective
   policy reading.
 - [CLI contract](docs/cli.md): the `version`, `check`, `publish`, `build`,

docs/consumers/adoption.md

@@ -0,0 +1,53 @@
+# Adopt ReleaseKit
+
+Use a versioned Go tool dependency when ReleaseKit provides the repository's
+release commands. This records the CLI in `go.mod` and keeps it available to
+maintainers without adding imports to application or library code.
+
+## CLI tool dependency
+
+From the consumer module's root, select the ReleaseKit version to adopt:
+
+```sh
+go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0
+go mod tidy
+go tool releasekit version
+```
+
+Replace `v0.2.0` with the intended release. Go records the executable package in
+a `tool` directive and the module version in a `require` directive. The tool
+declaration retains the dependency through `go mod tidy`. Commit the resulting
+`go.mod` and `go.sum` changes. To upgrade, repeat the command with the chosen
+version and review the module changes.
+
+Go tool dependencies require Go 1.24 or later, together with a toolchain that
+satisfies the selected ReleaseKit version and its dependencies. Tools share the
+consumer's module graph: their requirements participate in dependency version
+selection and can raise the consumer module's Go minimum. See the
+[Go tool dependency reference](https://go.dev/ref/mod#go-mod-file-tool).
+
+Run `go tool releasekit` from within the consumer module to use its selected
+version. Follow the [CLI contract](../cli.md) for commands and exit statuses,
+and the [configuration reference](../config.md) for the release profile.
+
+## Go API consumers
+
+Consumers importing the root `releasekit` API or
+[`buildinfo`](runtime-version.md) use ordinary package dependencies. Add the
+required imports and select the module version:
+
+```sh
+go get gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0
+go mod tidy
+```
+
+API consumers can also register the CLI with `go get -tool` as above. Both uses
+share the module-selected ReleaseKit version.
+
+## CI adoption
+
+The maintained [consumer tag-delivery workflow](delivery.md#woodpecker-tag-workflows)
+supports both tool and ordinary package dependencies. It builds ReleaseKit from
+the tagged consumer's module selection, so the committed module files also
+govern CI delivery and retries. Registering the CLI as a tool is sufficient for
+consumers that use ReleaseKit only for maintainer commands.

docs/consumers/delivery.md

@@ -154,7 +154,9 @@ image with Git and a Go toolchain compatible with the consumer module and its
 selected ReleaseKit version. Choose the patch used for the consumer's release
 build and validation. The template uses `GOTOOLCHAIN=local`; Go does not download
 a different toolchain. The tag's `go.mod` must select ReleaseKit as a module
-dependency.
+dependency. For CLI-only consumers, use the versioned Go tool dependency
+described in the [adoption guide](adoption.md). Ordinary package dependencies
+also work with this template.
 Configure the Woodpecker repository secret `releasekit_gitea_token`; the
 template maps it to `RELEASEKIT_GITEA_TOKEN` for delivery. The repository needs
 a `delivery` profile. Page-only and binary behavior both use this template; the