Standardize bots on GitHub App token, align merge methods, version PyPI via NBGV - #70

Mirrors the pattern from homeassistant-purpleair where we discovered
`gh pr merge --squash` against `main` would fail enablePullRequestAutoMerge
once a stricter ruleset is in place: the develop ruleset allows only
squash, the main ruleset allows only merge commits.

Workflow changes
- merge-bot-pull-request.yml `merge-dependabot`: switch to App token
  (`actions/create-github-app-token`) so the resulting merge push fires
  `publish-release.yml` on develop (GITHUB_TOKEN-driven pushes are
  blocked by GitHub's recursion guard). Replace the unconditional
  `--squash` with a `case` on `pull_request.base.ref` that picks
  `--squash` for develop and `--merge` for main, with an explicit
  failure for unknown bases.
- merge-bot-pull-request.yml `merge-codegen` and `merge-codegen-app`:
  both target `main` exclusively, so switch `--squash` → `--merge` to
  match the main ruleset. Stay on GITHUB_TOKEN — these merge routine
  generated-content updates and deliberately should not fire a release
  on every codegen tick.
- merge-bot-pull-request.yml header comment: rewritten to describe the
  current token strategy (App token vs GITHUB_TOKEN per job) and the
  merge-method dispatch rule.

Dependabot routing
- dependabot.yml: switch `target-branch: "main"` → `"develop"` on all
  three ecosystem entries (nuget, github-actions, uv). Scheduled bumps
  now land on develop first, then bundle into the next develop → main
  merge-commit alongside feature work — so develop cannot fall behind
  main. Security update PRs from Dependabot still open against `main`
  directly (Dependabot doesn't honor `target-branch` for those); the
  new `case` statement in the merge-bot handles either base.

Documentation
- AGENTS.md "Branching Model": new bullet describing Dependabot target
  routing and the merge-bot's base-aware method dispatch.
- .github/copilot-instructions.md "Commit Messages and Pull Request
  Titles": short paragraph about picking `--squash` vs `--merge` when
  running `gh pr merge` so AI agents asked to merge a PR pick the form
  that matches the base branch's ruleset.
- PyPiLibrary/README.md "Publishing": expanded the first-time PyPI
  Trusted Publishing setup with the lessons from today's release
  session — 2FA prerequisite, the pending-publisher vs add-new-publisher
  distinction, the mandatory `pypi` environment deployment branch rule
  for `main`, optional required reviewer, troubleshooting for both
  `invalid-publisher` and the `manifest unknown` Docker pull failure
  we hit before today's release, and an API-token fallback recipe.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

… App token

Two follow-ups on this branch:

NBGV-driven PyPI version
- build-pypilibrary-task.yml: add an inner `get-version` job (mirrors
  `build-nugetlibrary-task.yml`) and a new "Write version into
  _version.py step" that overwrites `_version.py` with NBGV's
  `AssemblyFileVersion` (Major.Minor.Patch.BuildNumber — always
  numeric, PEP 440 valid) just before `uv build`. Wheel and sdist
  carry the rewritten version, so the PyPI upload matches the
  NuGet/Docker/executable artifacts for the same release commit.
- PyPiLibrary/src/.../_version.py: docstring expanded to explain
  the `0.0.0` placeholder is a local-development convenience and
  that CI rewrites the file from NBGV.
- PyPiLibrary/README.md: stack table now lists Version alongside the
  other tooling; "Template Adoption" section now treats NBGV as the
  default and frames hatch-vcs / manual as alternatives.

Consolidate codegen and merge-bot on the GitHub App token
- Delete `run-codegen-app-pull-request-task.yml` and
  `run-periodic-codegen-app-pull-request.yml`. The App-based variant
  is now the only codegen path.
- Rewrite `run-codegen-pull-request-task.yml` with App-token logic
  (formerly only in the deleted *app* variant). No PAT, no close /
  reopen dance — App tokens trigger `pull_request` workflow events
  directly when opening a PR.
- `run-periodic-codegen-pull-request.yml`: drop the Monday/Thursday
  alternation note; weekly Monday cron + `workflow_dispatch` remain.
- `merge-bot-pull-request.yml`: delete the `merge-codegen-app` job
  and rewrite `merge-codegen` to use the App token, match
  `ptr727-codegen[bot]`, and skip the legacy `(reopened & owner) ||
  (not reopened & github-actions[bot])` actor dance. Both jobs in
  the file now use App tokens; header comment rewritten to reflect
  the new single-strategy model.
- README.md "Template - GitHub Setup": drop the WORKFLOW_PAT
  section, make the App setup required (was framed as an
  alternative), and collapse the dual-codegen-schedule section
  into a single weekly entry.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…f-gate

Two fixes for unresolved Copilot threads on the latest head (604fd27):

1. Dependabot can't see Actions secrets (`merge-bot-pull-request.yml:28`).
   Dependabot-triggered `pull_request` workflows run with a restricted
   secret context — `secrets.CODEGEN_APP_ID` and `CODEGEN_APP_PRIVATE_KEY`
   stored only in the Actions store aren't visible. README updated to
   instruct saving the App credentials in **both** the Actions and the
   Dependabot secret stores. No workflow change needed.

2. `publish-pypi` would stall on develop pushes
   (`PyPiLibrary/README.md:61` thread).
   `publish-release.yml` triggers on push to both `main` and `develop`.
   The `pypi` environment now restricts deployments to `main` only,
   so on a develop push the `publish-pypi` job would queue against an
   env it can't enter — visible as a stalled / blocked deployment on
   every develop release. Add `if: github.ref == 'refs/heads/main'` so
   the job is cleanly skipped on develop and the env rule remains as
   the security boundary. PyPiLibrary/README.md updated to explain the
   two-layer restriction.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot review on 6e5b400 caught that the docstring in _version.py and
the "Template Adoption" paragraph in PyPiLibrary/README.md both claimed
PyPI artifacts share the version of "matching NuGet, Docker, and
executable artifacts" — that overstates the parity. PyPI now uses
NBGV's `AssemblyFileVersion` (PEP 440 valid, Major.Minor.Patch.Build),
which matches the .NET assemblies' `FileVersion` / `AssemblyVersion`
stamp, but NuGet packages and Docker tags use NBGV's `SemVer2` (with
prerelease and build-metadata suffixes that PEP 440 doesn't accept).
Reword in three places (_version.py docstring, the Stack table entry,
and the Template Adoption paragraph) to spell out:

- PyPI string == .NET FileVersion/AssemblyVersion string (byte-equal).
- PyPI string != NuGet PackageVersion or Docker tag (different format).
- All four are derived from the same NBGV computation against
  version.json + git history, so they correspond to the same release
  commit even when the strings differ.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Third Copilot pass on PR #70 caught one more occurrence of the
overstated parity claim — this time in the inline comment above the
"Write version into _version.py step" in `build-pypilibrary-task.yml`.
Same fix as 55c9d86 applied here: PyPI equals .NET `FileVersion` /
`AssemblyVersion` (both = NBGV `AssemblyFileVersion`); NuGet
`PackageVersion` and Docker tags use NBGV `SemVer2` (different format,
not byte-identical); all four still derive from the same NBGV
computation per release commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per AGENTS.md workflow conventions, third-party actions used in
workflows being modified should be pinned to a commit SHA with a
trailing `# vX.Y.Z` comment. Two pins applied here:

- merge-bot-pull-request.yml: dependabot/fetch-metadata@v2 →
  21025c705c08248db411dc16f3619e6b5f9ea21a # v2.5.0 (same commit as
  the `v2` floating tag currently resolves to).
- run-codegen-pull-request-task.yml: peter-evans/create-pull-request@v8
  → 5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 (same commit as
  the `v8` floating tag currently resolves to).

The other third-party action flagged by Copilot — dotnet/nbgv@master
in get-version-task.yml — is declined here because AGENTS.md scopes
opportunistic pinning to workflows "being touched for other reasons"
and get-version-task.yml is unmodified in this PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…place

Copilot review on c8a38ef caught two issues:

(1) AssemblyVersion != AssemblyFileVersion. NBGV produces both as separate
    outputs and the build workflows wire them to distinct .NET properties
    (Version / AssemblyVersion = NBGV AssemblyVersion; FileVersion = NBGV
    AssemblyFileVersion). My earlier wording claimed PyPI matches both
    FileVersion *and* AssemblyVersion — that's only half-true. Rewording in
    four places (_version.py docstring, README "Version" stack entry,
    README "Template Adoption" section, workflow comment) to limit the
    parity claim to FileVersion only.

(2) `printf > _version.py` was truncating the file, so the published wheel
    would have lost the module docstring and any future metadata stored in
    `_version.py`. Switched the "Write version into _version.py step" to
    `sed -i` so only the `__version__` line is rewritten; the rest of the
    module is preserved into the build artifact.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>