fix(cli): make help and output modes predictable

[steipete]

Summary

• add Git-style command help and make help robust after trailing malformed arguments
• report setup and usage failures consistently on stderr
• make explicit JSON/plain flags override environment defaults and reject JSON transforms without JSON mode
• reject plain output for the JSON-only schema command
• remove self-referential Classroom roster aliases and enforce alias invariants
• update automation and generated command documentation

Verification

• make ci
• make docs-check
• focused CLI regression tests
• local binary smoke tests for help, diagnostics, schema output, JSON transforms, and environment precedence
• autoreview: no accepted/actionable findings

No live Google API calls are required; these changes affect local parsing, help, output-mode validation, and generated metadata.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 11, 2026, 7:06 PM ET / 23:06 UTC.

Summary
Review failed before ClawSweeper could summarize the requested change.

Reproducibility: unclear. The review failed before ClawSweeper could establish a reproduction path.

Review metrics: none identified.

Merge readiness
Overall: 🌊 off-meta tidepool
Proof: 🌊 off-meta tidepool
Patch quality: 🌊 off-meta tidepool
Result: rating does not apply to this item.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] No close action taken because the review did not complete.

Maintainer options:

1. Decide the mitigation before merge
   Retry the Codex review after fixing the execution failure.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• Review did not complete, so no work-lane recommendation was made.

Review details

Best possible solution:

Retry the Codex review after fixing the execution failure.

Do we have a high-confidence way to reproduce the issue?

Unclear. The review failed before ClawSweeper could establish a reproduction path.

Is this the best way to solve the issue?

Unclear. Retry the review first so ClawSweeper can evaluate the actual issue and fix direction.

AGENTS.md: unclear because the file could not be read completely.

Codex review notes: model internal, reasoning high; reviewed against 02291d290e87.

Label changes

Label changes:

• add rating: 🌊 off-meta tidepool: Overall readiness is 🌊 off-meta tidepool; proof is 🌊 off-meta tidepool and patch quality is 🌊 off-meta tidepool.

Label justifications:

• rating: 🌊 off-meta tidepool: Overall readiness is 🌊 off-meta tidepool; proof is 🌊 off-meta tidepool and patch quality is 🌊 off-meta tidepool.

Evidence reviewed

What I checked:

• failure reason: retryable codex transport failure.
• codex failure detail: Codex review failed for this PR with exit 1.
• codex stderr: eature":false,"requiresNewConfigOption":false,"requiresProductDecision":false,"reproductionAssessment":"Unclear; source and tests have not yet been fully inspected.","solutionAssessment":"Unclear; the proposed implementation is still under review.","visionFit":"not_applicable","visionFitReason":"Pull request review.","visionFitEvidence":[],"implementationComplexity":"not_applicable","autoImplementationCandidate":"none","agentsPolicyStatus":{"found":true,"readFully":false,"applied":false,"status":"unreadable_or_unclear","summary":"Repository policy review is in progress."},"reviewFindings":[],"securityReview":{"status":"not_applicable","summary":"Security review is still in progress.","concerns":[]},"realBehaviorProof":{"status":"missing","summary":"Proof assessment is still in progress.","evidenceKind":"none","needsContributorAction":true},"prRating":{"proofTier":"NA","patchTier":"NA","overallTier":"NA","summary":"Review in progress.","nextSteps":[]},"telegramVisibleProof":{"status":"not_needed","summary":"This is not a Telegram change."},"mantisRecommendation":{"status":"not_recommended","scenario":"none","reason":"This local CLI behavior is better verified with focused terminal evidence.","maintainerComment":""},"featureShowcase":{"status":"none","reason":"This is a corrective CLI consistency change rather than an exceptional new capability."},"overallCorrectness":"patch is correct","overallConfidenceScore":0.1,"fi.

Likely related people:

• unknown: Codex failed before it could trace repository history. (role: review did not complete; confidence: low)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7485e4745d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not append help after malformed command flags

When a user runs a Git-style help command with a partial or malformed flag, e.g. gog help drive ls --max nope or gog help send --body, this rewrite preserves those tokens before the synthetic --help. Kong will parse/validate them first, or may consume --help as the missing flag value, so this path can error or enter command validation instead of reliably showing help. This makes gog help <command> less robust than the new gog <command> --help truncation; drop trailing non-path arguments or insert the help flag before them.

Useful? React with 👍 / 👎.