From 09f2168ad2b114c207eb3da68dca4fcc5e4daacd Mon Sep 17 00:00:00 2001
From: "blu@blu.cx" <38222767+thebrandonlucas@users.noreply.github.com>
Date: Thu, 22 Oct 2026 15:38:15 -0500
Subject: [PATCH] docs: add a staging setup and a Try it section for each PR

The development guide gains a short block that aliases the staging wrapper,
builds, and logs in, for checking a pull request's branch by hand. AGENTS.md
and the pull request template ask each pull request for a "Try it on
staging" section: the exact commands to paste after that setup, every
changed help and docs example, and what to expect.
---
 .github/pull_request_template.md | 15 +++++++++++++++
 AGENTS.md                        | 25 +++++++++++++++++++++++++
 docs/development.md              | 14 ++++++++++++++
 3 files changed, 54 insertions(+)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index c98162c..7dfab98 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,7 +1,22 @@
 <!-- What changed for users, and why. Name the base PR if this is stacked. -->
 
+## Try it on staging
+
+<!-- See AGENTS.md "Try it on staging". Commands a reviewer pastes after the setup. -->
+
+Setup: [Try a pull request on staging](docs/development.md#try-a-pull-request-on-staging)
+
+```sh
+voltage ...
+```
+
+Expect: ...
+
+## Checks
+
 - [ ] User-visible change: a guide or reference under `docs/` and `CHANGELOG.md` (**Unreleased**) are updated, or the PR has the `no-changelog` label.
 - [ ] The verification gate in `docs/development.md` passes.
 - [ ] The diff was reviewed against its base with the `voltage-pr-review` skill, and every new error and early-return path has a test.
 - [ ] CRAP report, when `src/` or `tests/` changed: the highest score and each function at or above 20.
 - [ ] Checks not run, and why:
+- [ ] **Try it on staging** lists every changed `--help` and docs example, with what to expect.
diff --git a/AGENTS.md b/AGENTS.md
index e231d44..fc89d0f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,6 +33,31 @@ so a pull request is not ready until each one is done and reported.
 5. In the pull request description, give the checks you ran and the CRAP result: the
    highest score and each function at or above 20. Name any check you could not run, and
    why.
+6. In the pull request description, add a **Try it on staging** section that a reviewer can
+   paste after the [staging setup](docs/development.md#try-a-pull-request-on-staging).
+   See [Try it on staging](#try-it-on-staging).
+
+## Try it on staging
+
+The section tells a reviewer exactly what to run and what to look for. Write it for a
+reviewer who is on the branch and has run the setup, and nothing else:
+
+- Start with one line: `Setup: [Try a pull request on staging](docs/development.md#try-a-pull-request-on-staging)`.
+- Give the commands in `sh` blocks, ready to paste. Use `voltage` (the staging alias) and
+  `--account me`, never a profile the reviewer may not have. Use a placeholder only for a
+  value each reviewer has to supply, such as `WALLET_ID`, and say how to find it, such as
+  `voltage wallets list --account me`.
+- After each command or group, say what to expect in one line: the text, symbol, color, or
+  exit code that shows the change works.
+- List every `--help` and docs example that the pull request adds or changes, adapted to the
+  setup. To find them, run
+  `git diff origin/master...HEAD -- README.md docs src | grep '^+.*voltage '`.
+- Cover the variants the change affects, such as piped output (`2>&1 | cat`), `--json`,
+  `--quiet`, `--color never`, or `--no-input`.
+- Mark each command that sends a change. It needs `--execute` and a test-network wallet;
+  say so.
+- For a change with nothing to see, such as a refactor or a test-only change, write
+  `Nothing to try on staging` and the reason.
 
 A reviewer runs the CRAP report on the pull request's head and reports each violation as a
 finding, together with the review from step 1.
diff --git a/docs/development.md b/docs/development.md
index d7aca10..1aec35d 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -203,6 +203,20 @@ command line. A profile ignores `VOLTAGE_WALLET_ID` and the other ambient variab
 `--wallet` explicitly. Confirm a wallet's reported network is a test network before creating
 a payment. Browser login needs the device-login release deployed on the staging auth service.
 
+### Try a pull request on staging
+
+To check a pull request's change by hand, check out its branch, with `.env` filled in as in
+step 1 above, and paste this from the repository root:
+
+```sh
+alias voltage="$PWD/scripts/voltage-staging"
+voltage --build
+voltage login --account me --credential-store file
+```
+
+Then run the commands in the pull request's **Try it on staging** section; they assume this
+setup. After pulling new commits, run `voltage --build` again.
+
 ## Staging acceptance
 
 Complete these steps against the deployed staging services before publishing a release, and