docs(cli): clarify --project/--schemas precede the subcommand (#500)

[avrabe]

Small docs follow-up to the #502 revert. That revert left clap-internals jargon ("debug-asserts … next-id/link/snapshot diff") in the user-facing --help for --project. This moves the rationale to a plain // maintainer comment and makes the /// help user-facing: pass --project/--schemas before the subcommand (rivet -p <dir> validate), like git -C <dir> <cmd>.

Addresses the UX confusion in #500 (a misplaced --project errors with empty stdout) by surfacing the convention in --help. Leaves #500 open for the maintainer's call on whether to additionally support per-subcommand --project.

Doc-comment only, no logic change. Verified: cargo test -p rivet-cli --test cli_commands → 127 passed, 0 failed (full suite incl. help tests — applying last hour's lesson) · fmt/clippy exit 0.

🤖 Generated with Claude Code

[github-actions]

📐 Rivet artifact delta

No artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: c2be292	Previous: e94ac95	Ratio
store_insert/100	87796 ns/iter (± 528)	67654 ns/iter (± 3608)	1.30
store_insert/1000	948743 ns/iter (± 8097)	724588 ns/iter (± 3390)	1.31
store_lookup/100	1994 ns/iter (± 7)	1544 ns/iter (± 11)	1.29
store_lookup/1000	25058 ns/iter (± 94)	18836 ns/iter (± 320)	1.33
store_lookup/10000	373109 ns/iter (± 2842)	263616 ns/iter (± 2700)	1.42
store_by_type/100	97 ns/iter (± 0)	75 ns/iter (± 0)	1.29
store_by_type/1000	97 ns/iter (± 0)	75 ns/iter (± 0)	1.29
store_by_type/10000	97 ns/iter (± 0)	75 ns/iter (± 0)	1.29
schema_load_and_merge	1450512 ns/iter (± 18968)	1116285 ns/iter (± 18770)	1.30
link_graph_build/100	169357 ns/iter (± 2604)	127342 ns/iter (± 429)	1.33
link_graph_build/1000	1922558 ns/iter (± 14245)	1485700 ns/iter (± 14208)	1.29
validate/100	444811 ns/iter (± 1726)	339829 ns/iter (± 1166)	1.31
validate/1000	18197134 ns/iter (± 296573)	14380052 ns/iter (± 167404)	1.27
validate/10000	1452038318 ns/iter (± 16893673)	1146681493 ns/iter (± 7596817)	1.27
traceability_matrix/100	4245 ns/iter (± 31)	3230 ns/iter (± 7)	1.31
traceability_matrix/1000	44062 ns/iter (± 1158)	33990 ns/iter (± 530)	1.30
traceability_matrix/10000	737285 ns/iter (± 5748)	578137 ns/iter (± 2534)	1.28
diff/100	60861 ns/iter (± 184)	44967 ns/iter (± 425)	1.35
diff/1000	733635 ns/iter (± 2045)	518272 ns/iter (± 2497)	1.42
diff/10000	8496192 ns/iter (± 660094)	6244657 ns/iter (± 325897)	1.36
query/100	1182 ns/iter (± 3)	882 ns/iter (± 3)	1.34
query/1000	15275 ns/iter (± 47)	11308 ns/iter (± 17)	1.35
query/10000	241197 ns/iter (± 3208)	175603 ns/iter (± 2580)	1.37
document_parse/10	22145 ns/iter (± 37)	17265 ns/iter (± 41)	1.28
document_parse/100	157625 ns/iter (± 2040)	121441 ns/iter (± 356)	1.30
document_parse/1000	1489901 ns/iter (± 15901)	1148895 ns/iter (± 10832)	1.30

This comment was automatically generated by workflow using github-action-benchmark.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!