feat(cli): show examples and a guide link in every command's help

build.rs

@@ -5,7 +5,8 @@
 //! operation without a mapping, a mapping without an operation, or a mapping whose target is
 //! not a placeholder in the operation's path, so the two files cannot drift apart silently.
 //!
-//! It also stamps `voltage --version` with the git build it came from.
+//! It also stamps `voltage --version` with the git build it came from, and picks the docs
+//! ref that help links to.
 
 use serde_json::{Value, json};
 use std::{
@@ -134,30 +135,45 @@ fn operation_record(
     })
 }
 
-/// The Cargo version, then the git build it came from. A clean build of its own `vX.Y.Z`
-/// tag shows the commit and date, as `rustc --version` does. Any other build shows
-/// `git describe`, such as `v0.1.0-14-g0e6078b-dirty`, or a bare commit when no tag is
-/// reachable, so it cannot be mistaken for the release. Without a git checkout the version
-/// stands alone and the build still succeeds.
-fn version() -> String {
+/// What `voltage --version` prints and which docs its help links to.
+struct Build {
+    /// The Cargo version, then the git build it came from. A clean build of its own
+    /// `vX.Y.Z` tag shows the commit and date, as `rustc --version` does. Any other build
+    /// shows `git describe`, such as `v0.1.0-14-g0e6078b-dirty`, or a bare commit when no
+    /// tag is reachable, so it cannot be mistaken for the release. Without a git checkout
+    /// the version stands alone and the build still succeeds.
+    version: String,
+    /// The git ref of the docs that match this binary: the release tag for a clean build
+    /// of it, else `master`, because an unreleased page exists only there.
+    docs_ref: String,
+}
+
+fn build() -> Build {
     let package = env::var("CARGO_PKG_VERSION").expect("CARGO_PKG_VERSION");
+    let tag = format!("v{package}");
+    let unreleased = |version| Build {
+        version,
+        docs_ref: "master".to_owned(),
+    };
     // A non-empty prefix means this package is a subdirectory of some other repository.
     if git(&["rev-parse", "--show-prefix"]).is_some_and(|prefix| !prefix.is_empty()) {
-        return package;
+        return unreleased(package);
     }
     watch_git_state();
     let describe = [
         "describe", "--tags", "--match", "v[0-9]*", "--dirty", "--always",
     ];
     let Some(build) = git(&describe) else {
-        return package;
+        return unreleased(package);
     };
-    let build = if build == format!("v{package}") {
-        git(&["log", "-1", "--format=%h %cs"]).unwrap_or(build)
-    } else {
-        build
-    };
-    format!("{package} ({build})")
+    if build != tag {
+        return unreleased(format!("{package} ({build})"));
+    }
+    let commit = git(&["log", "-1", "--format=%h %cs"]).unwrap_or(build);
+    Build {
+        version: format!("{package} ({commit})"),
+        docs_ref: tag,
+    }
 }
 
 /// Trimmed stdout of a successful, non-empty git command. Optional locks are off so that
@@ -199,7 +215,9 @@ fn watch_git_state() {
 }
 
 fn main() {
-    println!("cargo:rustc-env=VOLTAGE_VERSION={}", version());
+    let build = build();
+    println!("cargo:rustc-env=VOLTAGE_VERSION={}", build.version);
+    println!("cargo:rustc-env=VOLTAGE_DOCS_REF={}", build.docs_ref);
     println!("cargo:rerun-if-changed={SNAPSHOT}");
     println!("cargo:rerun-if-changed={MAPPING}");
     let spec = read_json(SNAPSHOT);

docs/guides/requests.md

@@ -1,6 +1,6 @@
 # Requests
 
-Commands mirror the API contract; see [the command reference](../commands.md) for the full list with routes. Every command and group has descriptive `--help`; body-building commands also show required flag combinations and examples:
+Commands mirror the API contract; see [the command reference](../commands.md) for the full list with routes. `-h` shows a command's usage and options. `--help` adds its notes: required flag combinations, scope, examples for every command that changes something, and a "Learn more" link to the guide for the release you run:
 
 ```sh
 voltage --help

docs/guides/wallets.md

@@ -32,11 +32,11 @@ The ledger lists every credit, hold, capture, and release on the wallet. `--all`
 
 ```sh
 voltage wallets update WALLET_ID --profile prod --name operations --execute
-voltage wallets policies get WALLET_ID --profile prod
+voltage wallets policies get WALLET_ID --profile prod --json | jq .data > policies.json
 voltage wallets policies update WALLET_ID --profile prod --data @policies.json --execute
 ```
 
-Policies have no friendly flags: read the current policies, edit the JSON, and send the complete object with `--data`. Deleting a wallet cannot be undone, so check the request with a dry run first:
+Policies have no friendly flags: save the current policies, edit the file, and send the complete object with `--data`. Save only `.data`: `--json` and `--output-file` wrap the response in an envelope, which is not a policy body. Deleting a wallet cannot be undone, so check the request with a dry run first:
 
 ```sh
 voltage wallets delete WALLET_ID --profile prod --dry-run