Document the semantic, maintainer-controlled versioning policy

AGENTS.md

@@ -49,6 +49,9 @@ The template uses a **two-phase model by default**: PRs build fast, publishing i
     - *Source-only / no build* (validate + tag + release): you need none of the package/image leaf tasks - only your validation in `test-pull-request.yml`, one `release-asset-*` leaf task for the artifact you attach (or zero, if the release is just a tag), and the verbatim `get-version` + `github-release` + `date-badge` orchestration.
   - `get-version-task.yml` installs the .NET SDK only because NBGV needs the runtime to compute the version/tag - heavyweight but expected even for a non-.NET downstream; acceptable as-is.
 - **No-op republish guarantee.** A weekly/dispatch publish where NBGV `SemVer2` is **unchanged** (no new commit since the last publish) re-pushes **nothing** to GitHub Releases (the `github-release` job's `release-exists` check skips the create step), NuGet (`dotnet nuget push --skip-duplicate`), or PyPI (`gh-action-pypi-publish` `skip-existing: true`) - all three key on the version string. **Docker always re-pushes** by design: it picks up upstream base-image refreshes (e.g. `ubuntu:rolling`) that aren't visible in the repo. Boundary: `version.json` has **no `pathFilters`**, so *any* commit - including a CI/workflow-only or docs-only change - advances the NBGV git height and therefore `SemVer2`, and the next publish *does* create a fresh release for it even when the shipped binary is byte-identical. This is accepted NBGV behavior; `pathFilters` are intentionally not added.
+- **Versioning is semantic and maintainer-controlled.** The `version` (major.minor) in [`version.json`](./version.json) is the version floor; NBGV appends the git height for the build version. `main` builds the stable release (`major.minor.height`); `develop` builds a prerelease (`major.minor.height-g{sha}`). The maintainer edits `version.json`; dependency bumps, CI/workflow fixes, doc edits, and template re-syncs leave it untouched.
+  - **`develop` leads `main` by a minor.** After a `develop -> main` release lands and main's publish completes, bump the minor in `version.json` on `develop` in an isolated `bump-version-X.Y` PR (squash to develop). This keeps every develop prerelease numerically above main's last stable: at a shared version, develop's prerelease `X.Y.height-g{sha}` sorts *below* main's stable `X.Y.N` in `--version`, `HISTORY.md`, and consumer update prompts, and the lead avoids that.
+  - **A maintenance `develop -> main` promotion holds main's version.** Catch-up work - dependency bumps, CI/doc fixes, template re-syncs - reaches `main` without releasing develop's leading minor: run `git checkout main -- version.json` on the promotion branch before opening the PR, so `main` advances by a patch and `develop` keeps its lead. A release promotion instead carries develop's version to `main`, and `develop` then bumps again to restore the lead.
 
 ## Pull Request Title and Commit Message Conventions