Complete module release documentation

docs/consumers/adoption.md

@@ -20,10 +20,11 @@ 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
+The Go tool dependency feature requires Go 1.24 or later. The current ReleaseKit
+module declares a Go 1.26.0 minimum, so use Go 1.26.0 or later for the current
+release. Tool dependencies 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

docs/consumers/check.md

@@ -21,6 +21,17 @@ if err != nil {
 fmt.Println(result.Version, result.Commit)
 ```
 
+Set `ReleaseRequest.ModuleDir` to select a nested module using a
+repository-relative physical directory; omission or `.` selects the root
+module. ReleaseKit reads that module's committed `go.mod` and returns its
+physical `ModuleDir`, declared `ModulePath`, semantic `Version`, and complete
+`Tag` in the candidate and result. A physical `/v2` directory is removed from
+the tag prefix only when the declared module path also ends in `/v2`. For
+example, both `integrations/core/v2` and `integrations/core` can declare
+`example.com/project/integrations/core/v2` and use the tag
+`integrations/core/v2.1.0`. The release note lives under the physical module at
+`<module>/docs/releases/<version>.md`.
+
 The repository must have a clean index and worktree on `main`, and the selected
 version must be stable `vMAJOR.MINOR.PATCH`. The committed
 `docs/releases/<version>.md` note must have a first Markdown H1 containing the
@@ -79,7 +90,19 @@ standard suite, selected vet/format/distribution checks, or Markdown navigation
 checks in `AdditionalChecks` or profile `checks`. Keep release-note rules and
 consumer-specific assertions—such as tests of maintained examples—in those
 product-owned checks.
-ReleaseKit calls `AdditionalChecks` once after shared validation when supplied.
+The `Candidate` supplies both `RepositoryDir` and `ModuleDir`, plus the declared
+`ModulePath`, semantic `Version`, and full `Tag`; use its module directory for
+module-local product checks. ReleaseKit calls `AdditionalChecks` once after
+shared validation when supplied.
+
+`ValidationSpec.SharedFiles` adds committed, repository-relative files to
+ReleaseKit's optional file checks without enabling any checks. A nil slice
+selects the optional defaults `COPYRIGHT`, `LICENSE`, and
+`docs/oss/attribution.md`, when present; a non-nil empty slice selects none.
+Explicit files replace those defaults, must exist even when file checks are
+disabled, and may be in another module. Combined inputs are deduplicated by
+repository-relative path.
+
 It does not download a different toolchain automatically. If race prerequisites
 are unavailable, the `go-test` check fails rather than being skipped; a selected
 full-vet failure is reported as `go-vet`. The suite uses the Go host target,

docs/consumers/delivery.md

@@ -27,7 +27,7 @@ or hosted content.
 ```go
 err := releasekit.PrepareTaggedCheckout(ctx, releasekit.TaggedCheckoutRequest{
     RepositoryDir:  repositoryDir,
-    Version:        version,
+    Tag:            "integrations/example/v1.2.3",
     ExpectedCommit: ciCommit,
 })
 if err != nil {
@@ -42,11 +42,18 @@ module with workspace discovery disabled and the available compatible local Go
 toolchain.
 The operation may use the network and updates the Go module cache while
 preserving the caller's proxy, private-module, credential, and cache settings.
-If checksums are missing, Go may update `go.sum`; see the
+If checksums are missing, Go may update `go.sum`. For binary CI delivery, prepare
+and commit the selected module's `go.sum` before tagging: delivery verifies the
+tagged source remains clean after dependency preparation. See the
 [Go Modules Reference](https://go.dev/ref/mod#go-mod-download). Cancellation
 and command errors are returned. Page-only profiles do not need dependency
 preparation.
 
+Set `TaggedCheckoutRequest.VerifyOnly` when a bootstrap step already fetched and
+detached the event tag. This mode checks the exact tag, expected commit, `HEAD`,
+and clean worktree without fetching or changing the checkout. Both modes require
+the full `Tag` and expected commit.
+
 ## Command line
 
 Add a Gitea destination to the profile:
@@ -199,10 +206,21 @@ without another fetch or checkout. It loads the tagged profile and downloads
 application dependencies only when build targets are selected; it builds and
 delivers those targets with the note page. Source-only profiles skip application
 dependency downloads and binary work. Dependency preparation for binaries may
-use the network and may update an uncommitted checksum file in the checkout. A
+use the network. Prepare and commit the selected module's `go.sum` before
+tagging; an uncommitted change makes the later delivery source check fail. A
 retry still uses the same immutable tag and that tag's module settings, even
 after the default branch selects a newer ReleaseKit version.
 
+The root-only [`tag-delivery.yml`](../../examples/woodpecker/tag-delivery.yml)
+keeps the small default profile and root-module bootstrap. For consumers that
+release several modules from one repository, copy the contents of the maintained
+[multi-module example](../../examples/multi-module/) to the consumer repository
+root and use its [`woodpecker.yml`](../../examples/multi-module/woodpecker.yml),
+[`release-modules.tsv`](../../examples/multi-module/release-modules.tsv), and
+shared selector. The event tag chooses one row from the tagged checkout; the
+profile and physical module must agree, and ReleaseKit verifies the derived tag.
+The example covers source-only integration pages and a binary core module.
+
 If the application does not declare ReleaseKit as a module dependency, install
 the executable separately and invoke the same `ci-deliver` command. For
 ReleaseKit's own source workflow, the maintained

docs/consumers/publish.md

@@ -6,6 +6,7 @@ annotated source tag:
 ```go
 result, err := releasekit.Publish(ctx, releasekit.ReleaseRequest{
 	RepositoryDir:   "/work/project",
+	ModuleDir:       "integrations/example",
 	Product:         "Example",
 	Version:         "v1.2.3",
 	ExpectedPushURL: "ssh://git.example/owner/example.git",
@@ -19,9 +20,22 @@ result, err := releasekit.Publish(ctx, releasekit.ReleaseRequest{
 if err != nil {
 	return err
 }
-fmt.Println(result.Version, result.CandidateCommit, result.TagObject)
+fmt.Println(result.ModulePath, result.Version, result.Tag, result.CandidateCommit, result.TagObject)
 ```
 
+`ModuleDir` is a repository-relative physical module directory; omit it or use
+`.` for a root-module release. ReleaseKit reads the selected module's committed
+declaration and derives the complete Git tag from its declared module path and
+physical location. `Version` remains the stable semantic version. The note is
+`<module>/docs/releases/<version>.md`; an on-disk `/v2` directory is part of
+the note path but is removed from the tag prefix only when the module path ends
+in `/v2`. `PublicationResult` returns the absolute `ModuleDir`, declared
+`ModulePath`, complete `Tag`, and existing commit and tag-object evidence.
+
+The optional `ValidationSpec.SharedFiles` selects additional committed files
+for enabled file checks. Its nil and empty-slice behavior is described in the
+[candidate check guide](check.md#local-candidate-check).
+
 Publication captures a clean candidate on `main`, validates its committed
 release note, and checks the selected remote before running candidate checks.
 Set `ExpectedPushURL` to require the effective push destination to match an