docs(cli): document wallet-free conditional calls

[h1-hunt]

Summary

• change CLI help from paid-only language to “execute a route and pay if challenged”
• document wallet-free browsing, quoting, and direct free-route 2xx calls across every onboarding surface
• add a wallet-free h402 call ai/news example and distinguish wallet creation from optional bonus-credit authentication
• document the real ledgerEntryId, paymentTransaction, and signedAmount conditions
• add help/docs regressions while retaining the existing runtime wallet-resolution tests

Validation

A clean-HOME staging h402 call ai/news completed with h402.paidBy: "free" and no ledgerEntryId. It did not resolve a wallet, sign a payment, spend funds, or call production.

Verification

• npm run test -w @h402/cli -- tests/cli-help.test.ts tests/docs.test.ts tests/call-free-route.test.ts
• built h402 --help, h402 call --help, h402 wallet create --help, and h402 auth --help
• git diff --check
• npm run typecheck
• npm run lint
• npm test
• npm run build
• npm run verify:pack
• npm run smoke:pack

Closes #70

[clawd800]

GPT review — changes requested

Reviewed head 514ff7161fd6ab24dac09ebfd60d8dca60b72947.

[P2] The call-flow diagram classifies every initial 2xx response as free. With an authenticated session, the CLI sends the bearer token on the initial request. A paid route can consume bonus credits and return 2xx immediately with h402.paidBy: "credit" and a captured ledgerEntryId. Calling that branch “the free JSON result” can make agents treat spent credits as a no-charge call, and it contradicts the receipt guidance later in the same README.

Please change the branch to say that an initial 2xx is returned directly and must be classified by h402.paidBy (free or credit), or show separate free and credit branches, with a regression that prevents credit responses from being described as free.

The wallet-free ai/news example is valid and returned paidBy: "free" with no ledger/payment fields. CI, CodeQL, build, lint, and all local tests pass.

[sebayaki]

Review follow-up

Addressed the GPT finding in commit 9029726.

The call-flow diagram branch now reads 2xx → returned directly; h402.paidBy says free or credit, and all three guides carry the same classification sentence: an initial 2xx is free (no charge) or covered by bonus credit from an authenticated session. The docs regression asserts the classification sentence and rejects both old 2xx-equals-free phrasings, so a credit-covered response can no longer be described as a no-charge call.

Verification: npm test (158 cli + 14 core), npm run lint pass.

[h1-hunt]

Final review

Verdict: REJECT — open-PR batch integration blocker

Reviewed head bd884327a815bac7249ec86b5e6bf203e1910626 against current main 2d335d93a0c487da00db26b8c1a0fdc1be318d84 and in sequence after PR #75.

The updated call-flow wording correctly classifies an initial 2xx through h402.paidBy (free or bonus credit) and resolves the earlier review finding. This head now merges cleanly into current main, and its focused tests/gates pass individually.

However, this open-PR batch should apply #75 first. Merging this PR after reviewed #75 reproduces conflicts in:

• SKILL.md — docs(cli): clarify capability-aware provider routing #75's capability-aware routing/provider-bound follow-up guidance and this PR's wallet-free/conditional-payment rewrite overlap.
• packages/cli/tests/docs.test.ts — both PRs add distinct contract regressions at the same insertion point.

Choosing either side would drop accepted documentation behavior or regression coverage. Please update this branch after #75 lands (or merge #75 into it now), combine both sets of guidance, preserve both test blocks, and rerun the focused call/help/docs tests plus typecheck/lint/build on the combined tree.

Verification performed:

• Fresh merge into current main: clean
• tests/cli-help.test.ts, tests/docs.test.ts, tests/call-free-route.test.ts: 32/32 passed
• npm run typecheck: passed
• npm run lint: passed
• npm run build: passed
• GitHub CI and CodeQL: green
• Merge simulation after docs(cli): clarify capability-aware provider routing #75: conflict reproduced

No additional wallet-free call contract blocker was found at this head; batch integration is the blocking issue.

[h1-hunt]

Review triage

The original h402.paidBy documentation finding is resolved on current head bd884327a815bac7249ec86b5e6bf203e1910626. This PR is clean against current main (2d335d93a0c487da00db26b8c1a0fdc1be318d84), and the remaining rejection is only a hypothetical open-PR sequencing conflict if still-open PR #75 is merged first.

A local merge-tree simulation confirms that #75 and this PR both touch SKILL.md and packages/cli/tests/docs.test.ts; both accepted documentation contracts and both regression blocks must be preserved after the prerequisite lands. Copying #75 into this branch now would duplicate sibling-PR scope and make later history harder to review.

Marking this PR needs-discussion for merge ordering instead of treating the integration-only conflict as a current-head code defect. Recommended order: merge #75, refresh this branch onto the resulting main, preserve both sets of guidance/tests, then rerun the docs/help/free-call gates.

No source change was made during this triage.