fix(docs): reject ambiguous tab reads

[kiranmagic7]

Summary

• reject docs cat --tab ... --all-tabs before contacting the Docs API
• apply the same mutually-exclusive validation to raw docs cat reads
• reject ambiguous docs_get MCP inputs when both tab and all_tabs are provided

Behavior proof

The built CLI exits with a usage error when both tab selectors are provided; there is no auth prompt or API response:

$ ./bin/gog docs cat doc-redacted --tab Overview --all-tabs
--tab and --all-tabs cannot be used together

Exit status: 2.

Raw reads hit the same validation:

$ ./bin/gog docs cat doc-redacted --raw --tab Overview --all-tabs
--tab and --all-tabs cannot be used together

Exit status: 2.

Verification

• go test ./internal/cmd -run "TestDocsCat_RejectsTabWithAllTabs|TestMCPDocsGetRejectsTabWithAllTabs" -count=1
• go test ./...
• go vet ./...
• make build
• make test
• git diff --check

No changelog entry; this is a small validation fix for an ambiguous flag combination.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 14, 2026, 12:03 AM ET / 04:03 UTC.

Summary
The PR adds fail-fast validation for ambiguous and blank Docs tab selectors in docs cat and MCP docs_get, plus regression tests and an unreleased changelog note.

Reproducibility: yes. Source inspection of current main shows CLI and MCP paths accept both selectors independently, and the PR body includes after-fix live CLI output for the new failure path.

Review metrics: 2 noteworthy metrics.

• Touched surface: 6 files changed; 105 additions, 5 deletions. The diff is small but changes both CLI and MCP user-facing argument validation.
• Regression coverage: 2 test functions added; 2 direct-call updates. The new tests cover normal/raw Docs reads and MCP docs_get, while direct Run calls are updated for the new Kong context parameter.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

• none.

Risk before merge

• [P1] Merging this intentionally turns currently accepted CLI and MCP inputs into usage errors when clients send both a single-tab selector and all-tabs selector, or an explicitly blank tab selector.

Maintainer options:

1. Accept fail-fast validation (recommended)
   Treat the combined selector input as unsupported ambiguity and land the PR after normal checks because it now rejects before auth or Docs API work.
2. Preserve legacy tolerance
   If existing scripts or MCP clients must keep sending both selectors, revise the PR to keep the current precedence and document that behavior instead of rejecting it.

Next step before merge

• [P2] The remaining action is maintainer acceptance of the compatibility change, not an automated code repair.

Security
Cleared: The diff only changes local argument validation, tests, and release-note text; it does not touch secrets, dependencies, workflows, or supply-chain execution paths.

Review details

Best possible solution:

Land the focused validation if maintainers accept fail-fast behavior for unsupported ambiguous inputs; otherwise preserve and document the existing permissive precedence.

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

Yes. Source inspection of current main shows CLI and MCP paths accept both selectors independently, and the PR body includes after-fix live CLI output for the new failure path.

Is this the best way to solve the issue?

Yes, if maintainers accept the compatibility break. Early validation in the CLI command and MCP argument builder is the narrow repair, with preserving the current permissive behavior as the safer alternative if compatibility wins.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is a small validation improvement for an ambiguous Docs CLI/MCP argument combination.
• merge-risk: 🚨 compatibility: The PR intentionally turns currently accepted CLI/MCP selector inputs into usage errors for existing users or clients.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes copied after-fix CLI output from the built binary showing the new usage error and exit status for normal and raw ambiguous reads.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied after-fix CLI output from the built binary showing the new usage error and exit status for normal and raw ambiguous reads.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR review guidance says to inspect with gh pr view / gh pr diff without changing branches or code, which matched this read-only review. (AGENTS.md:31, c57fb9dab6d3)
• Current-main CLI behavior: DocsCatCmd.Run on current main validates the doc ID, then raw and tab-aware reads evaluate c.Tab and c.AllTabs independently, so a caller can currently send both selectors through to the Docs read path. (internal/cmd/docs_read.go:38, c57fb9dab6d3)
• Current-main MCP behavior: mcpDocsGetTool appends --tab and --all-tabs independently when both MCP arguments are present, matching the ambiguous behavior the PR changes. (internal/cmd/mcp_tools.go:177, c57fb9dab6d3)
• Existing validation precedent: docs raw already rejects --tab with --all-tabs, which supports the PR's consistency direction for docs cat and MCP docs_get. (internal/cmd/docs.go:89, c57fb9dab6d3)
• PR CLI implementation: The PR head trims and validates --tab, detects explicit empty tab flags through Kong context, and rejects --tab with --all-tabs before creating the Docs service. (internal/cmd/docs_read.go:33, 79c1f7be3889)
• PR MCP implementation: The PR head rejects empty tab input and mutually exclusive tab plus all_tabs in the MCP argument builder before constructing CLI args. (internal/cmd/mcp_tools.go:177, 79c1f7be3889)

Likely related people:

• steipete: Current-main blame points the Docs read and MCP Docs lines at the release commit by Peter Steinberger, and recent history shows Peter authored the tab-aware raw output and several adjacent Docs features. (role: recent area contributor and adjacent feature owner; confidence: high; commits: 3a66566be7a4, 0a7e6425384b, 96529accf58f; files: internal/cmd/docs_read.go, internal/cmd/docs.go, internal/cmd/mcp_tools.go)
• alexknowshtml: GitHub commit metadata for the original Docs tab-support commit shows Alex Hillman authored the change that added docs cat --all-tabs and docs cat --tab behavior. (role: introduced related behavior; confidence: high; commits: 2f5131995552; files: internal/cmd/docs.go, internal/cmd/docs_commands_test.go)
• auroracapital: GitHub commit metadata shows the typed MCP server commit introduced mcp_tools.go and mcp_test.go, including the docs_get argument-building surface affected here. (role: introduced MCP tool surface; confidence: high; commits: e6bad02932cf; files: internal/cmd/mcp_tools.go, internal/cmd/mcp_test.go)

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.

[steipete]

Landed with maintainer hardening in 9cf00cb:

• docs cat --tab ... --all-tabs now fails locally before constructing or contacting the Docs service.
• Whitespace-only and explicitly empty --tab= values are rejected consistently.
• Raw CLI reads and MCP docs_get enforce the same selector contract.
• Regression tests count Docs API requests and prove all invalid CLI paths make zero requests.
• Added the maintainer changelog entry crediting @kiranmagic7.

Verification:

• GOTOOLCHAIN=go1.26.2 make ci
• /Users/steipete/Projects/agent-skills/skills/autoreview/scripts/autoreview --mode branch --base origin/main --parallel-tests 'GOTOOLCHAIN=go1.26.2 make ci' --stream-engine-output returned no actionable findings with 0.93 confidence.
• Built CLI: conflicting selectors returned exit code 2 with --tab and --all-tabs cannot be used together.
• Built CLI: --raw --tab= --all-tabs returned exit code 2 with --tab cannot be empty.
• Exact-head GitHub checks passed for 79c1f7be3889c1d7d6d76d72d69e0c7627d1e29b: Linux test, Windows, Darwin cgo build, worker, and Docker image.

Thanks @kiranmagic7.