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 **deliberate** version floor; NBGV appends the git height for the actual build version. **Bump it only for a real release** - new features or significant changes the maintainer judges worth a new version. **Routine maintenance does not bump it**: dependency bumps, CI/workflow fixes, doc edits, and template re-syncs land on `main` as a new *patch* of the current version, never a new minor. There is **no automatic versioning** - the file changes only when someone edits it.
+  - **`develop` and `main` normally share the same `version.json`.** `develop` is the prerelease channel of the current version (`X.Y-prerelease.gSHA`); `main` is the release (`X.Y.height`). **`develop` is not required to "lead" `main`**, and you should **not preemptively bump** "for the next cycle" - bump when you actually cut the feature release. (A premature develop-side bump is what forces the awkward "promote maintenance without the version" dance below; avoid creating it.)
+  - **Promoting `develop -> main` carries `version.json` as-is.** If the maintainer bumped it, the promotion *is* the release of that version. If it's unchanged (maintenance/catch-up), `main` simply advances a patch - nothing special to do. **If `develop`'s version was bumped ahead of `main` but you want to promote only maintenance** (not release the new version yet), hold the version on the promotion branch: `git checkout main -- version.json` before opening the PR, so `main` keeps its current version. This is the exception, not the routine.
 
 ## Pull Request Title and Commit Message Conventions