Repository navigation
docs: add troubleshooting, getting started, a changelog, its CI check, and a PR template - #29
Merged
Conversation
This was referenced Oct 13, 2026
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
2 times, most recently
from
October 19, 2026 13:14
2d19d0b to
61af70c
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
4 times, most recently
from
October 19, 2026 18:39
a0df0b3 to
d6b3fc3
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
2 times, most recently
from
October 19, 2026 19:11
b4ca251 to
39b720c
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 19, 2026 19:19
39b720c to
ba7701d
Compare
This was referenced Oct 19, 2026
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 00:20
ba7701d to
01df020
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 11:59
01df020 to
ad2267b
Compare
This was referenced Oct 20, 2026
This was referenced Oct 20, 2026
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 12:25
ad2267b to
293198d
Compare
tee8z
self-requested a review
October 20, 2026 12:34
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 13:01
293198d to
1b6d033
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 15:17
1b6d033 to
a42169d
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 15:32
a42169d to
7c99bae
Compare
tee8z
requested changes
Oct 20, 2026
tee8z
left a comment
Contributor
There was a problem hiding this comment.
One line repeats the auth_url_mismatch advice that #19 fixed; everything else matched the code (exit codes, quoted errors, anchors), and the changelog workflow and PR template look right. CRAP on 7c99bae: no function at or above 20, highest api::wait_for_payment at 19.24; the full test suite passed in the same run.
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 16:12
7c99bae to
5b9f6b8
Compare
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 16:36
5b9f6b8 to
574e085
Compare
…, and a PR template docs/guides/troubleshooting.md is keyed by exit code and by each credential_problem name, with the fix for each; a test requires an entry for every exit code and every CredentialProblem, which exhaustive matches keep complete. docs/getting-started.md walks from install to a settled mutinynet payment and a scripted receive. CHANGELOG.md starts with the changes since 0.1.0. A Changelog workflow fails a PR that changes src/cli.rs or api/commands.json without CHANGELOG.md, unless it has the no-changelog label. AGENTS.md states the rule and that the check is a heuristic. The pull request template asks for the changelog entry, the verification gate, the review checks, the CRAP result, and any check not run with its reason. The docs example checks now also read CHANGELOG.md and the tutorial, so their commands parse and their changes pass as offline dry runs.
thebrandonlucas
force-pushed
the
docs/cli-troubleshooting
branch
from
October 20, 2026 16:51
574e085 to
ffbf63c
Compare
tee8z
self-requested a review
October 20, 2026 16:52
tee8z
approved these changes
Oct 20, 2026
3 of 5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack: master ← #26 ← #27 ← #28 ← #29 ← #30 ← #55 ← #60. #20, #22, #57, #24 and #19 are merged.
docs/guides/troubleshooting.md): an entry per exit code and percredential_problem(no_credential,multiple_credentials,unknown_credential,empty_api_key,bound_elsewhere,auth_url_mismatch), plus expired logins, API-key discovery, HTTP 401/403 (account and checkout credentials), a locked OS credential store,feature_flag_disabled, andquote_required. Each heading is the literal code or message, so search finds it.docs/getting-started.md): one path from install through login, a saved profile, a mutinynet wallet, a received 1,000 sats, and the same receive scripted with--jsonandjq.CHANGELOG.md(Keep a Changelog style, hand-written) seeded with the changes since 0.1.0, including this stack.Changelogworkflow fails a PR that changessrc/cli.rsorapi/commands.jsonwithoutCHANGELOG.md, unless it has theno-changeloglabel. It reruns on label changes, so it is a separate workflow from CI.AGENTS.mdstates the rule and that the check is a heuristic: it fires on test-onlysrc/cli.rschanges and misses user-visible changes in other files.voltage-pr-reviewpass with tests for new error paths, the CRAP result (highest score and each function at or above 20), and each check not run with its reason, asAGENTS.md"Before you request review" requires.Tests: troubleshooting must have an entry for every exit code and every
CredentialProblem. The exit codes come from #28'serror_kinds()and the problems from an exhaustivematch, so a new kind or problem fails to compile until it has an entry. The docs example checks also readCHANGELOG.mdand the tutorial, so the tutorial's commands parse and its changes pass as offline dry runs.Changes after review
error_kinds()instead of a hard-coded list.tests/support/examples.rsis now rustfmt-clean;cargo fmtdoes not reach it because it is included withinclude!.auth_url_mismatchentry (from feat(cli): report auth_url in context, time waits, and list items one per line #19). The 401/403 entries cover checkout tokens, and thequote_requiredentry matches feat(cli): name the next command in scope, credential, and login errors #24's wording.no-changeloglabel now exists in the repository.Not done here
Checks
On
574e085:cargo fmt --check,cargo clippy --locked --all-targets -- -D warnings,cargo machete --with-metadata: pass.cargo test --locked: 103 unit and 86 integration tests pass.VOLTAGE_BLESS=1 cargo test --lockedleaves the tree clean.python3 scripts/check-coverage.py: pass.scripts/crap-report.sh): no function at or above 20. Highest isapi::wait_for_paymentat 19.24, unchanged from or lower than master (19.66).voltage-pr-reviewand thevoltage-backend-engineeringRust checklist, against the stack base. Findings are fixed in this commit.Not run: the staging and live tutorials, which need credentials.