build: advice is to always use github action latest

README.md

@@ -4,6 +4,8 @@
 
 Consuming repositories own configuration; they do not own pipeline source code. Version, paths, feature switches, and release-mode selection are per-repository.
 
+[![Release](https://github.com/purview-dev/build/actions/workflows/release.yml/badge.svg)](https://github.com/purview-dev/build/actions/workflows/release.yml)
+
 ## Delivery surfaces
 
 The same implementation is available three ways:
@@ -14,6 +16,14 @@ The same implementation is available three ways:
 
 ## Minimal repository setup (reusable workflow)
 
+The examples below reference the workflows at `@main`, so they always run the latest version of the workflow/action code. The `@ref` suffix is required for cross-repository references and resolves the workflow/action to a specific commit; there is no `@latest`. Pin a release tag (e.g. `@v0.2.0`) instead if you want reproducible workflow code.
+
+> **Two independent version axes.** The `@ref` selects the workflow/action *code*, while the
+> `build-version` input selects the installed `Purview.Build` *tool*. Omit `build-version` to
+> always install the latest stable tool, or pin it (e.g. `build-version: 0.2.0`) for
+> reproducibility. Mixing a pinned old `@ref` with a floating `build-version` runs newer tool
+> code through older workflow inputs.
+
 ```yaml
 # .github/workflows/pr.yml
 name: PR
@@ -22,7 +32,7 @@ on:
     branches: [main]
 jobs:
   build:
-    uses: purview-dev/build/.github/workflows/purview-build.yml@v0.2.0
+    uses: purview-dev/build/.github/workflows/purview-build.yml@main
     # `build-version` is optional; when omitted, the latest stable Purview.Build
     # from nuget.org is installed. Pin it (e.g. `build-version: 0.2.0`) for
     # reproducible builds.
@@ -37,7 +47,7 @@ on:
     branches: [main]
 jobs:
   release:
-    uses: purview-dev/build/.github/workflows/purview-release.yml@v0.2.0
+    uses: purview-dev/build/.github/workflows/purview-release.yml@main
     with:
       release-mode: NuGet
     secrets: inherit
@@ -63,7 +73,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: purview-dev/build/.github/actions/purview-build@v0.2.0
+      - uses: purview-dev/build/.github/actions/purview-build@main
         env:
           Build__TestFilter: "/*/*/*/*[Category=Unit]"
 ```
@@ -120,4 +130,4 @@ This repository dogfoods the shared tool: CI builds and packs the tool from sour
 
 On a push to `main`, the release workflow rebuilds and reinstalls the tool from the current source, then runs it with `Release__Mode=NuGet`, `NuGet__FeedUrl` pointing at nuget.org, and `Release__UploadArtifacts=true`. The tool therefore publishes the immutable package to `https://api.nuget.org/v3/index.json` and tags and releases itself (`v{Version}` + generated-notes GitHub release with the package attached) — exactly like every other purview-dev repository. Maintainers bump the `package.json` version and merge; they do not create release tags manually.
 
-GitHub initially creates NuGet packages as private. To make sure every package is **Internal** (consumable by all Purview-Dev members), an organization owner should set the org default: Purview-Dev → Settings → Packages → **Package Creation** → **Internal**, and change any already-published package's visibility in its **Package settings** → **Danger Zone**. See [docs/releasing.md](docs/releasing.md) for the exact steps and the `gh api` alternative.
+GitHub initially creates NuGet packages as private. To make sure every package is **Internal** (consumable by all Purview-Dev members), an organization owner should set the org default: Purview-Dev → Settings → Packages → **Package Creation** → **Internal**, and change any already-published package's visibility in its **Package settings** → **Danger Zone**. See [docs/releasing.md](docs/releasing.md) for the exact steps and the `gh api` alternative.

docs/releasing.md

@@ -6,7 +6,7 @@
 - Minor: additive options or modules with backward-compatible defaults.
 - Major: renamed/removed keys, changed defaults with material effects, or a required runtime upgrade.
 
-The reusable workflows and composite action default `build-version` to the latest stable `Purview.Build` release from nuget.org; omit the input to always run the newest version. Consumers that need reproducibility pin an exact version via the `build-version` input (and, for local use, `.config/dotnet-tools.json`). Automated dependency updates should open a pull request, where the consumer's normal build validates the new tool before merge. Keep the previous major supported while migrations are in progress.
+The reusable workflows and composite action are referenced with an `@ref` suffix (required for cross-repository references), which selects the workflow/action *code*: `@main` always runs the latest code, while a release tag (e.g. `@v0.2.0`) pins it for reproducibility. `build-version` is an independent axis that selects the installed `Purview.Build` *tool*; it defaults to the latest stable release from nuget.org, and consumers that need reproducibility pin an exact version via the `build-version` input (and, for local use, `.config/dotnet-tools.json`). Automated dependency updates should open a pull request, where the consumer's normal build validates the new tool before merge. Keep the previous major supported while migrations are in progress.
 
 The version is declared by the `version` field in the repository's root `package.json`. Releasing consists of bumping that field and merging the validated pull request into the release head.