docs(cli): clarify capability-aware provider routing

[h1-hunt]

Summary

• document that auto capability-routes provider-native input to a compatible enabled candidate
• reserve --provider for deterministic/deliberate selection and provider-bound async follow-ups
• translate h402.followUp metadata into a concrete CLI polling template in every agent-facing guide
• add a docs regression covering both routing rules

Validation

A clean-HOME, unpaid staging quote for web/search with provider-native freshness: "week" succeeded on the auto route and selected search:locus-brave. No payment was signed or made.

Verification

• npm run test -w @h402/cli -- tests/docs.test.ts
• git diff --check
• npm run typecheck
• npm run lint
• npm test
• npm run build
• npm run verify:pack
• npm run smoke:pack

Closes #69

[clawd800]

GPT review — changes requested

Reviewed head c1be140d0aff467188832212d4a74354ca6fe3b6.

[P2] The new follow-up template only works for GET pollers. The template in all three guides hardcodes --query and omits h402.followUp.method. An enabled current follow-up, ai/music-status-async on provider locus-suno, is POST. Instantiating the documented template against staging sent GET and returned HTTP 405 (Use POST for this route). Adding --method POST does not repair it because the CLI explicitly rejects POST combined with --query; POST follow-ups require --json.

Please make the guidance method-aware (GET → --query, POST → --json) and add regression coverage for both forms. The current docs test instead locks in the invalid universal --query template.

Capability-aware auto routing itself validated successfully, and CI, CodeQL, build, lint, and all local tests pass.

[sebayaki]

Review follow-up

Addressed the GPT finding in commit 79e4e1e.

The follow-up CLI template is now method-aware in all three guides: GET follow-ups keep --query '<followUp.params>', and a second POST form uses --json '<followUp.params>' with ai/music-status-async called out as the concrete POST example. The intro sentence states the rule explicitly (the CLI rejects --query on a POST), and the docs regression now asserts both forms plus the method-matching sentence instead of locking in the universal --query template.

Verification: npm test (docs suite + full run), npm run lint pass.

[h1-hunt]

GPT Reviewer

Verdict: PASS

Reviewed head 277dfb0bf7bc3dfd244f2ec56b787e98bf7a2f89 against current base 2d335d93a0c487da00db26b8c1a0fdc1be318d84 using a bounded, tool-free review bundle.

The documentation consistently explains capability-aware auto routing and provides correct, method-aware GET and POST templates for provider-bound follow-ups. Regression coverage spans all three guides, and all supplied validation passed.

Findings

None.

Shared exact-snapshot validation

• diff-check: PASS (0.0s)
• npm-ci: PASS (1.493s)
• typecheck: PASS (3.746s)
• lint: PASS (2.765s)
• test: PASS (3.76s)
• build: PASS (2.519s)
• No paid h402/provider calls were made.

[h1-hunt]

Opus Reviewer

Verdict: PASS

Reviewed head 277dfb0bf7bc3dfd244f2ec56b787e98bf7a2f89 against current base 2d335d93a0c487da00db26b8c1a0fdc1be318d84 using a bounded, tool-free review bundle.

Docs-only PR (plus a docs regression test) that clarifies capability-aware auto routing and makes the async follow-up CLI template method-aware. The changes correctly resolve the prior GPT review (P2): GET follow-ups poll via --query, POST follow-ups (e.g. ai/music-status-async) via --json, matching the CLI flag semantics (--json sets POST; --query is GET-only; the CLI rejects --query on a POST). The auto-routing prose is appropriately hedged and was validated on staging (freshness on the auto route selecting search:locus-brave). All three guides (README.md, SKILL.md, packages/cli/README.md) receive identical, internally consistent content, and the new regression test asserts both GET/POST forms and the method-matching sentence while guarding against the removed "requires pinning" caveat. Existing docs tests remain satisfied (meta/envelope/token-holder assertions unaffected), Markdown fencing (including the indented list code block in SKILL.md) is valid, and shared validation passes (diff-check, npm ci, typecheck, lint, 171 tests, build). I considered the <followUp.routeId> vs <provider-from-followUp.path> notation asymmetry but the deliberate difference is best explained by routeId being a real followUp field while provider is derived from the provider-bound path, so it is not high-confidence an error. No actionable findings.

Findings

None.

Shared exact-snapshot validation

• diff-check: PASS (0.0s)
• npm-ci: PASS (1.493s)
• typecheck: PASS (3.746s)
• lint: PASS (2.765s)
• test: PASS (3.76s)
• build: PASS (2.519s)
• No paid h402/provider calls were made.