docs: point contributors at develop and the intent block

AGENTS.md, CONTRIBUTING.md, and desktop/docs/services-backend.md all still told
contributors to bump services/versions.json by hand, which CI now rejects.
services/readme.md and the pull request template were updated when the rule
landed; these three were missed. The internal job that used to enforce this is
stripped from the public cut, so for public contributors the rule is new and
the docs are the only thing announcing it.

CONTRIBUTING.md also told contributors to branch from main and never named
develop, walking them straight into a pull request whose declared bumps would
be discarded on merge.

Records four limits that were real but undocumented: apply resolves only the
head commit's pull request, so develop must take one merge per push; the apply
workflow must not gain a concurrency group; a literal '### ' line truncates a
changelog body; and the gate assumes branch protection requires the check.
Also notes that the app and its two settings must exist before the first push
to develop.

Signed-off-by: Terve <ntervalon@nvidia.com>

Author: Noah-Tervalon-Nvidia

.github/PULL_REQUEST_TEMPLATE.md

@@ -11,6 +11,8 @@
 <!-- Set the title and body to n/a when no bump is a release. -->
 <!-- The release version users see is NOT declared here: it patch-bumps by
      itself whenever any bump above is a release. -->
+<!-- Keep the changelog body to prose and bullets. A line starting with "### "
+     ends the section and silently truncates the rest. -->
 
 <!-- pair-release-intent:v1 -->
 ### Changelog title

AGENTS.md

@@ -123,9 +123,11 @@ On Windows, run the underlying npm and `go test` commands directly.
   service, the broker relay, every consumer, the desktop bridge under
   `desktop/src/electron/service-bridge/`, the tests, and the documentation in the
   same change. Then run `npm run service-contracts:check` from `desktop/`.
-- **Bump the version of any service binary whose compiled output you change** in
-  `services/versions.json`, and describe any user-facing change in the pull
-  request so it reaches the release notes.
+- **Declare a bump for any service binary whose compiled output you change** in
+  the `pair-release-intent:v1` block in your pull request description, and
+  describe any user-facing change there so it reaches the changelog. Do not edit
+  `services/versions.json` or `CHANGELOG.md` by hand — automation writes them,
+  and CI rejects a pull request that modifies them.
   [Versioning](services/VERSIONING.md) gives the rules.
 - **Sign off every commit** with `git commit -s`. The Developer Certificate of
   Origin trailer has to match the commit author, so a missing or mismatched

CONTRIBUTING.md

@@ -245,11 +245,20 @@ screenshots and examples.
 
 ## Versions
 
-When your change alters a service binary's compiled output, bump that component
-in `services/versions.json` in the same pull request.
+When your change alters a service binary's compiled output, declare that bump in
+the `pair-release-intent:v1` block in your pull request description. The pull
+request template contains the block; fill in the severity for each component and
+write the changelog title and body there.
+
+**Do not edit `services/versions.json` or `CHANGELOG.md` by hand.** Automation
+writes both after your pull request merges, and CI rejects a pull request that
+modifies them. If you are adding or removing a component — something the bot
+cannot infer — include `<!-- pair-release-intent-allow-owned-files -->` in the
+description to override that check.
+
 [Versioning](services/VERSIONING.md) gives the rules for choosing a patch, minor,
-or major bump, and covers the `desktop/package.json` version, which follows its
-own release cycle.
+or major bump, and explains the three version numbers and which of them you are
+expected to declare.
 
 Say in the pull-request description which components you bumped and why, so a
 reviewer can check the decision rather than infer it from the diff.
@@ -264,7 +273,9 @@ clear description is what makes a change show up there correctly.
 Anyone may submit a pull request. Follow this checklist:
 
 1. Fork the repository.
-2. Create a focused branch from `main` in your fork.
+2. Create a focused branch from `develop` in your fork, and open the pull
+   request against `develop`. That is the integration branch; `main` receives
+   `develop` periodically as a release cut.
 3. Explain the problem and observable desired outcome.
 4. State what is intentionally in and out of scope.
 5. Add or update tests and documentation.

desktop/docs/services-backend.md

@@ -310,8 +310,10 @@ The build is cache-aware. CI passes `--force`. Packaging validates that
 
 2. Review component version changes, emitted notifications, handled requests,
    and new binary components, then regenerate `docs/services-api.md` with
-   `service-contracts:write`. Bump the affected components in
-   `services/versions.json` as `services/VERSIONING.md` describes. Do not
+   `service-contracts:write`. Declare bumps for the affected components in the
+   pull request's `pair-release-intent:v1` block as `services/VERSIONING.md`
+   describes; `services/versions.json` is written by automation and CI rejects
+   a hand edit. Do not
    hardcode product or component versions in this document or
    `docs/services-parity.md` — `service-contracts:check` fails if they appear.
 3. Read the changed backend `README.md` / `spec.md` and the Go implementation.

scripts/release-intent/README.md

@@ -61,6 +61,30 @@ pieces and a window where the changelog names a version `package.json` does not
 yet carry. Moving the ref once avoids that, and a rejected fast-forward is the
 concurrency check — the script retries that and only that, up to three times.
 
+## Known limits
+
+**One apply per push.** `apply_pr.py` resolves the pull request for the push's
+head commit only. A push carrying two merges — a direct push of a range, or a
+merge-queue batch — applies the head commit's intent and **silently skips the
+others**. Nothing fails. `develop` must therefore take one merge per push: no
+merge queue batching, and no pushing a range of merge commits directly. Lifting
+this means iterating the push's commits rather than reading only the head.
+
+**No concurrency group on the apply workflow, on purpose.** GitHub keeps a
+single pending run per group and cancels any earlier one, so under a burst of
+merges a group would drop bumps rather than serialize them. Ordering is handled
+in the script instead, by committing with `force: false` and re-reading the ref
+when the branch moved. Do not add one.
+
+**`### ` inside a changelog body truncates it.** `_parse_section` ends a section
+at the next line beginning with `### `, so a body containing a literal `### `
+line is silently cut at that point. Keep changelog bodies to prose and bullets.
+
+**The gate assumes branch protection.** `develop` should require the
+`Release intent check` status check. An admin merge that bypasses it with an
+invalid block fails at apply with exit 1, loudly, but the versions simply do not
+bump until someone fixes the body and re-runs.
+
 ## Idempotency
 
 Each bot commit carries an `Applies-PR: #N` trailer, and every attempt scans the
@@ -80,6 +104,7 @@ and expiring in an hour.
 - Configure `RELEASE_INTENT_APP_ID` as a repository variable and
   `RELEASE_INTENT_APP_PRIVATE_KEY` as a secret.
 
+**The app and both settings must exist before the first push to `develop`.**
 If the credential is missing, `apply_pr.py` exits 2 and says so rather than
 silently skipping the bump. Backfill by re-running the job once it is configured,
 or apply from a saved body locally.