feat(docs): add document enumerator commands

[TurboTheTurtle]

Summary

• add gog docs tables/images/headings/paragraphs list read-only enumerator subcommands
• support tab-scoped enumeration, JSON arrays, TSV --plain, and readable default output
• add focused command/enumerator tests and regenerate command reference docs

Fixes #719

Validation

• go test ./internal/cmd -run 'TestDocsEnumerate|TestDocsHeadingsList_TabJSON|TestDocsParagraphsList_PlainTSV'
• go test ./internal/cmd
• make docs-commands
• make fmt
• make ci

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed June 10, 2026, 1:11 AM ET / 05:11 UTC.

Summary
The branch adds read-only gog docs tables/images/headings/paragraphs list commands, shared enumerator code and tests, and regenerated command reference docs.

Reproducibility: not applicable. for a new feature PR: source review can verify the command shape, but there is no broken current-main behavior to reproduce. The missing evidence is live Google Docs output from the new commands, not a bug reproduction path.

Review metrics: 2 noteworthy metrics.

• Diff size: 14 files, 1249 additions, 1 deletion. Most changes are generated docs, but reviewers still need to focus on the executable enumerator code and tests.
• Behavioral surface: 3 code/test files and 11 docs files. The merge-relevant behavior is concentrated in the new enumerator implementation, command registry entry, and focused tests.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

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

Rank-up moves:

• [P1] Add redacted live output, a terminal screenshot, recording, linked artifact, or logs showing at least one new enumerator against a real Google Doc.

Proof guidance:

• [P1] Needs real behavior proof before merge: No after-fix real Google Docs output, terminal screenshot, recording, linked artifact, or redacted logs are provided; the contributor should add redacted proof and update the PR body to trigger re-review, or ask a maintainer to comment @clawsweeper re-review if needed.

Risk before merge

• [P1] The new commands depend on real Google Docs API response shapes, and the PR still has no redacted live output proving the enumerators work against a real document after the tab-image fix.

Maintainer options:

1. Decide the mitigation before merge
   Land the command family after the contributor adds redacted live output or a terminal screenshot showing the enumerators against a real Google Doc, followed by normal maintainer review.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] Contributor action is needed for redacted live Google Docs proof before merge; there is no narrow automated code repair remaining from this review.

Security
Cleared: The diff adds read-only Docs API enumeration code, tests, and generated docs without new dependencies, workflows, secret handling, or supply-chain changes.

Review details

Best possible solution:

Land the command family after the contributor adds redacted live output or a terminal screenshot showing the enumerators against a real Google Doc, followed by normal maintainer review.

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

Not applicable for a new feature PR: source review can verify the command shape, but there is no broken current-main behavior to reproduce. The missing evidence is live Google Docs output from the new commands, not a bug reproduction path.

Is this the best way to solve the issue?

Yes, based on source review this is a narrow implementation path for exposing indices and object IDs that existing Docs write commands consume. The remaining blocker is real Google Docs behavior proof, not a different code direction.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 0a7e6425384b.

Label changes

Label justifications:

• P2: This is a normal-priority Google Docs CLI feature with clear workflow value, limited blast radius, and no urgent regression signal.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: No after-fix real Google Docs output, terminal screenshot, recording, linked artifact, or redacted logs are provided; the contributor should add redacted proof and update the PR body to trigger re-review, or ask a maintainer to comment @clawsweeper re-review if needed.

Evidence reviewed

What I checked:

• Repository policy read: The full target AGENTS.md was read and applied as review context, including review-mode expectations and generated-docs guidance. (AGENTS.md:1, 0a7e6425384b)
• Current main lacks these commands: A targeted search on current main found no command structs or generated command pages for the new enumerator family; only an aspirational docs/sedmat.md mention exists. (internal/cmd/docs.go:21, 0a7e6425384b)
• PR implementation shape: The PR head defines the four new command groups and list commands, with JSON, TSV/plain, and readable output paths. (internal/cmd/docs_enumerators.go:18, e906e3dcf268)
• Earlier tab-image concern addressed: The selected-tab path now uses tab.DocumentTab.Body.Content plus the selected tab's inline and positioned object maps, and the new test covers that behavior. (internal/cmd/docs_enumerators.go:248, e906e3dcf268)
• Focused tests added: The PR adds unit coverage for tables, images, tab object maps, headings, paragraphs, JSON tab output, and TSV paragraph output. (internal/cmd/docs_enumerators_test.go:16, e906e3dcf268)
• Real behavior proof missing: The contributor reported local tests and CI commands, then stated live Google Docs proof is blocked because credentials are not configured; no redacted live output, screenshot, recording, linked artifact, or logs are present.

Likely related people:

• Peter Steinberger: Git blame and log history show the current Docs command registry, raw tab projection, and adjacent Docs helper surface come from recent mainline work by this author. (role: recent area contributor; confidence: high; commits: 71a8504d0add, 0a7e6425384b; files: internal/cmd/docs.go, internal/cmd/docs_read.go, internal/cmd/docs_paragraphs.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.

[TurboTheTurtle]

@clawsweeper re-review

Addressed the tab-scoped image object map finding in e906e3d. Local validation on the updated branch:

• go test ./internal/cmd -run 'TestDocsEnumerate|TestDocsHeadingsList_TabJSON|TestDocsParagraphsList_PlainTSV'\n- go test ./internal/cmd\n- make ci\n\nLive Google Docs proof is blocked in this environment because gog auth status --json reports no configured credentials and GOG_ACCESS_TOKEN is unset.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27254586675
• Updated: 2026-06-10T05:13:18.958Z

[TurboTheTurtle]

Closing this as superseded by merged upstream PR #726, which closes #719 and adds the content enumerator command surface. This branch now conflicts with main and no longer needs to stay open.