Best possible solution:

Land the focused command after maintainer command-shape confirmation and green CI, preserving the existing table selector, tab, dry-run, revision-control, output, docs, and test patterns.

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

Not applicable as a bug reproduction; this is a feature PR. Source inspection confirms current main lacks a pin-header command, while the PR adds that surface.

Is this the best way to solve the issue?

Yes, pending maintainer acceptance of the public command shape. The implementation follows the existing Docs table selection, tab targeting, revision-controlled request, output, test, and generated-doc patterns.

AGENTS.md: found and applied where relevant.

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

Label changes:

• add P3: This is a useful but optional Docs feature with limited blast radius and no broken existing behavior.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator-authored PR; the body nevertheless reports make ci plus live Google Docs API and render validation.

Label justifications:

• P3: This is a useful but optional Docs feature with limited blast radius and no broken existing behavior.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this collaborator-authored PR; the body nevertheless reports make ci plus live Google Docs API and render validation.

What I checked:

• Repository policy read: AGENTS.md was read fully; its PR-review-mode guidance to inspect the diff without switching branches or changing code was applied. (AGENTS.md:1, 42017c5e8ca8)
• Current main lacks pin-header: Current main registers table-row insert, delete, and style only, so the requested pin-header command is not already implemented. (internal/cmd/docs_table_ops.go:18, 42017c5e8ca8)
• Current row-style surface is adjacent but not duplicate: Current main exposes min-height and prevent-overflow through UpdateTableRowStyle, but not PinTableHeaderRows or a tableHeader flag. (internal/cmd/docs_table_row_style.go:15, 42017c5e8ca8)
• Existing helpers match the proposed implementation path: Current main already has shared table selection and revision-controlled batch helpers that the PR reuses for the new mutation. (internal/cmd/docs_table_ops.go:320, 42017c5e8ca8)
• PR diff reviewed: The PR adds one focused command implementation, one focused test file, generated command docs, and a small row-style output helper refactor; no actionable diff defect was found. (internal/cmd/docs_table_pin_header.go:1, ac7179660327)
• Linked feature request: The linked issue explicitly requests exposing PinTableHeaderRows as part of broader Docs table styling work, and remains open as the canonical umbrella.

Likely related people:

• steipete: Blame and recent merged PR history show this person authored the current table-row style command and recently expanded the Docs table styling surface that this PR extends. (role: recent Docs table area contributor; confidence: high; commits: 42017c5e8ca8, 42de13590640; files: internal/cmd/docs_table_ops.go, internal/cmd/docs_table_row_style.go, internal/cmd/docs.go)
• sebsnyk: This person opened the linked umbrella issue describing the missing PinTableHeaderRows behavior and is credited in the PR's user-facing changelog entry. (role: feature requester; confidence: medium)

• 🦀 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.

• 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.