Separate example setup from synthetic test releases

docs/consumers/adoption.md

@@ -9,12 +9,16 @@ maintainers without adding imports to application or library code.
 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
+: "${RELEASEKIT_TOOL_VERSION:?Set the released ReleaseKit version to adopt}"
+go get -tool "gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@${RELEASEKIT_TOOL_VERSION}"
 go mod tidy
 go tool releasekit version
 ```
 
-Replace `v0.2.0` with the intended release. Go records the executable package in
+Select a release that implements the API, profile, and workflow you are adopting.
+The module-release interface requires a release containing that feature;
+pre-feature versions through v0.3.0 use their corresponding historical interface.
+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
@@ -38,7 +42,8 @@ Consumers importing the root `releasekit` API or
 required imports and select the module version:
 
 ```sh
-go get gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0
+: "${RELEASEKIT_TOOL_VERSION:?Set the released ReleaseKit version to adopt}"
+go get "gitea.maximumdirect.net/eric/ReleaseKit@${RELEASEKIT_TOOL_VERSION}"
 go mod tidy
 ```
 
@@ -52,3 +57,10 @@ 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.
+
+Upgrade the module-selected tool and workflow together. For a tag created before
+that upgrade, retry with the workflow matching the tool recorded at that tag.
+Keep its immutable module files and tag intact. See the
+[delivery guide](delivery.md#woodpecker-tag-workflows) for tagged-source bootstrap
+and the [example's source verification](../../examples/multi-module/README.md#local-source-verification)
+for testing an unreleased checkout in a disposable consumer repository.

docs/consumers/delivery.md

@@ -185,6 +185,11 @@ a different toolchain. The tag's `go.mod` must select ReleaseKit as a module
 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.
+
+Select a tool release implementing this workflow's interface before adopting it;
+the [adoption guide](adoption.md#ci-adoption) owns coordinated tool/workflow
+upgrades. Retries of older tags use the workflow matching their recorded tool.
+
 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

docs/roadmap/next-release-notes.md

@@ -64,6 +64,13 @@ Update callers, profiles, receipts, and CI declarations together for this
 clean interface cutover; compatibility shims and legacy receipt readers are
 not provided.
 
+Select this feature's ReleaseKit release in each consumer module before adopting
+the new profiles and workflows. Upgrade its tool declaration and workflow
+together: pre-feature tools through v0.3.0 require their historical profiles and
+flags. Historical tag retries use the workflow matching the tool recorded at
+that tag. Preserve the immutable
+tag and module files when retrying.
+
 - Set `ModuleDir` in Go requests or `module_dir` in profiles for a nested
   module. The selected directory must contain its own `go.mod`; module paths
   and release tags are read from that declaration, not inferred from a folder
@@ -102,3 +109,11 @@ For current behavior, see the [API and consumer guides](../consumers/),
 [CLI contract](../cli.md), [configuration reference](../config.md),
 [Gitea integration](../integrations/gitea.md), and
 [ReleaseKit release procedure](../release.md).
+
+## Release preparation
+
+Once this release's version is selected, record it in the maintained multi-module
+example's tool and require directives, and move these notes to its release-note
+path. Example setup currently selects a compatible version explicitly; disposable
+fixtures can verify current source before publication. Synthetic dependency
+versions belong to generated test metadata and local fixture proxies.

docs/roadmap/remediation.md

@@ -293,7 +293,16 @@ coverage.
 
 ## Issue 9: Separate synthetic bootstrap versions from maintained examples (P2)
 
-Status: open. Category: broken adoption example and incomplete cutover guidance.
+Status: complete. Category: broken adoption example and incomplete cutover guidance.
+
+**Completion:** Maintained module skeletons no longer pin synthetic releases.
+Example setup explicitly selects compatible released tooling and documents source
+verification in disposable checkouts. Workflow fixtures generate their synthetic
+declarations. Current-source tool registration and all three example profiles,
+including native version injection, pass offline; mapped launchers/workflows and
+tagged-tool retries retain isolated fixtures. Adoption and migration guidance
+cover coordinated tool/workflow upgrades and historical retries. The pending
+release notes record concrete example pins as normal version-selection work.
 
 **Evidence:** All three maintained
 [multi-module declarations](../../examples/multi-module/) require ReleaseKit