The staging wrapper rejects --build with a command #37

What happened

The goal was to log in to staging with a fresh build. The agent ran:

scripts/voltage-staging --build login --account me --credential-store file

It exited with code 2:

error: unexpected argument '--build' found
Usage: voltage --config-dir <DIR> --auth-url <URL> --api-url <URL> <COMMAND>

The wrapper accepts --build only as its sole argument (args == ["--build"]). In all
other cases it passes --build to the binary, and clap rejects it. The agent needed a
second call to build and a third to log in.

Why it was confusing

• docs/development.md puts voltage --build in an alias block, so it looks like a flag
  that you can combine with a command.
• The error comes from clap, and the usage line shows the flags that the wrapper inserts
  (--config-dir, --auth-url, --api-url). Nothing in the error names the wrapper.
• Cheapest fix: in the wrapper, accept a leading --build, build, and then run the rest
  of the arguments. Alternatively, reject the mixed form with a wrapper message:
  "run scripts/voltage-staging --build alone first".

Provenance

• Found 2026-10-14 during a Claude Code session ("log in to voltage staging").
• Branch feat/cli-human-output, commit a060712, voltage 0.1.0 (a060712).
• Deployment: staging, through scripts/voltage-staging.

Status on other branches

No unmerged branch changes this behavior. feat/cli-error-hints and later branches only
skip voltage --build in their help-example tests.

Reproduction

repro.sh needs only a .env with the staging URLs. It makes no network calls.

# docs/issues/2026-10-14-staging-wrapper-build-flag/repro.sh
#!/usr/bin/env bash
PIN=a060712
source "$(git rev-parse --show-toplevel)/docs/issues/lib.sh"
build
try --build --help   # expected: build, then help. actual: exit 2 from clap

#!/usr/bin/env bash
# Shared setup for issue reproductions. Source it from a repro.sh after setting PIN.
set -euo pipefail
root=$(git rev-parse --show-toplevel)
cd "$root"
head=$(git rev-parse --short HEAD)
if [ "${PIN:-}" != "" ] && [ "$head" != "$PIN" ]; then
  echo "note: HEAD is $head; the issue was found at $PIN (git switch --detach $PIN to match)" >&2
fi
voltage() { "$root/scripts/voltage-staging" "$@"; }
need() { for v in "$@"; do [ -n "${!v:-}" ] || { echo "set $v first" >&2; exit 64; }; done; }
build() { "$root/scripts/voltage-staging" --build >/dev/null 2>&1; }
# Run a command, print its exit code, and never stop the script.
try() { echo "\$ voltage $*" >&2; set +e; voltage "$@"; echo "exit=$?" >&2; set -e; }

Run with nix develop --command ./docs/issues/2026-10-14-staging-wrapper-build-flag/repro.sh (see the agent friction log in AGENTS.md, #33).