feat(docs): add --at <text> anchor to insert / delete / update / insert-person / insert-page-break

[sebsnyk]

Motivation

gog docs insert-image --at <placeholder> already follows the "anchor by text" pattern and is much friendlier than --index=N. The sibling commands insert, delete, update, insert-person, insert-page-break all still require numeric indices, forcing callers into the same docs raw walk pattern over and over.

Once find-range (#682) lands, these can be implemented as thin wrappers.

Depends on

• feat(docs): add find-range primitive that maps text to Document index ranges #682 find-range primitive — --at <text> resolves the anchor by calling the same range-finder. Without feat(docs): add find-range primitive that maps text to Document index ranges #682 the implementation reproduces the walk-and-index logic per command; with feat(docs): add find-range primitive that maps text to Document index ranges #682 each --at is a one-call resolver into the existing index-based path.

Verified against current source (v0.21.x):

• docs_insert_page_break.go exposes --index + --at-end only; no --at <text>.
• docs_format.go flag set is bold/italic/underline/strike/font-family/font-size/text-color/bg-color/alignment/line-spacing/heading-level/named-style — no text-anchor.
• docs_insert_image.go is the only command with name:"at".

Repro

Today, to insert a Person chip at a specific name occurrence inside a doc body, a script has to:

1. gog docs raw and walk for the matching textRun.
2. gog docs delete --start=S --end=E to remove the existing run.
3. gog docs insert-person --email=... --index=S.

Three calls per chip, with the indices recomputed in reverse-document order to avoid drift.

Proposed surface

Add the following flags to each command:

--at <text>            Anchor by literal text
--occurrence INT       Disambiguate when multiple matches (default 1)
--match-case           Case-sensitive match

Per command behaviour:

• delete --at <text> — delete the matched range. Mutually exclusive with --start/--end.
• insert --at <text> — insert at the start index of the match (does not replace; for replace, use update).
• update --at <text> — replace the matched range with --text/--file content. Mutually exclusive with --index/--replace-range.
• insert-person --at <text> — atomic delete-and-insert-chip in one batchUpdate.
• insert-page-break --at <text> — insert at the start index of the match.

When the match is ambiguous and --occurrence is not set, exit non-zero with a hint listing all occurrences.

Acceptance criteria

• All five commands accept --at <text> and the result is identical to the current --index/--start/--end form when fed the resolved range.
• Ambiguous matches without --occurrence produce an error before mutating.
• insert-person --at is atomic (single batchUpdate request bundling DeleteContentRange + the InsertText/InsertPerson sequence), so concurrent writers cannot see an intermediate state.

References

• batchUpdate Request shape: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request
• DeleteContentRangeRequest + InsertTextRequest: same page
• InsertPersonRequest: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#InsertPersonRequest
• Existing precedent inside gog: gog docs insert-image --at <text> in internal/cmd/docs_insert_image.go

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 4, 2026, 8:36 AM ET / 12:36 UTC.

Summary
Keep open: current main still lacks the requested text-anchor flags on all five Docs mutation commands, and the linked shared range-finder prerequisite is still open, so this remains active feature/product sequencing work.

Reproducibility: not applicable. as a bug reproduction, but the missing feature is source-reproducible: current command structs and generated docs lack the requested --at flags on the five named commands.

Ways to help us reproduce this

• Add expected vs actual behavior.
• Include redacted logs or terminal output.
• Share version, platform, channel/provider, and relevant config details.

Next step
A maintainer should decide sequencing with the open range-finder work before this becomes a focused implementation task.

Review details

Best possible solution:

Land the shared range resolver first, then add consistent --at wrappers to the five commands while preserving the existing numeric index/range flags.

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

Not applicable as a bug reproduction, but the missing feature is source-reproducible: current command structs and generated docs lack the requested --at flags on the five named commands.

Is this the best way to solve the issue?

Yes on direction, not yet on sequencing: using a shared range finder is the maintainable shape, while duplicating textRun walking in each command before #682 would be the wrong path.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The requested surface depends on the open shared range-resolution work at feat(docs): add find-range primitive that maps text to Document index ranges #682; implementing this independently would duplicate Docs textRun/index walking across commands.
• The insert-person --at acceptance criteria require a single atomic batchUpdate path, so the eventual implementation needs focused unit coverage and live Google proof before merge.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d5c9cef65fa.

Label changes

Label justifications:

• P2: This is a concrete Docs CLI improvement with clear user value and limited blast radius, but it is not an urgent regression.
• impact:other: The issue affects scriptability and ergonomics of Docs mutation workflows, which is maintainer-visible but outside the specific owned impact classes.

Evidence reviewed

What I checked:

• Current main checked: The review was performed on current main at 3d5c9ce. (3d5c9cef65fa)
• Insert and delete still use numeric ranges: DocsInsertCmd exposes --index, and DocsDeleteCmd exposes required --start/--end; neither command struct has an --at anchor flag. (internal/cmd/docs_edit.go:746, 3d5c9cef65fa)
• Update still uses index or replace-range: DocsUpdateCmd exposes --index and --replace-range, with no text-anchor flag on the current command surface. (internal/cmd/docs_edit.go:524, 3d5c9cef65fa)
• Person chip and page break still use index/end: DocsInsertPersonCmd and DocsInsertPageBreakCmd expose --index/--at-end style placement rather than --at <text>. (internal/cmd/docs_smart_chips.go:16, 3d5c9cef65fa)
• Existing precedent is insert-image only: DocsInsertImageCmd has the existing At string flag, matching the issue's stated precedent and showing the requested pattern is not generalized yet. (internal/cmd/docs_insert_image.go:22, 3d5c9cef65fa)
• Shared range primitive is absent: Searching current source and docs found no find-range command or helper, so the issue's proposed dependency is not implemented on main. (3d5c9cef65fa)

Likely related people:

• Peter Steinberger: git blame attributes the current Docs mutation command structs and the existing insert-image --at precedent to the v0.21.0 release commit authored by Peter Steinberger. (role: current implementation provenance; confidence: medium; commits: 2c84d8981dd5; files: internal/cmd/docs_edit.go, internal/cmd/docs_insert_image.go, internal/cmd/docs_insert_page_break.go)
• sebsnyk: The changelog credits docs insert-image, the only existing --at precedent, to @sebsnyk, and the same contributor authored this issue and the linked range-finder prerequisite. (role: precedent and feature-shape contributor; confidence: medium; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/docs_insert_image.go)
• rel: The changelog credits the adjacent docs update --markdown and --replace-range work to @rel, which is relevant to the requested update --at behavior. (role: adjacent Docs update contributor; confidence: low; commits: 2c84d8981dd5; files: CHANGELOG.md, internal/cmd/docs_edit.go)

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 in c7b9ef6.

Implemented --at, --occurrence, and --match-case anchors for docs insert, docs delete, docs update, docs insert-person, and docs insert-page-break. Anchored mutations resolve through the shared Docs range finder, reject ambiguous/no-match cases before mutation, pin writes to the resolved revision, and keep insert-person --at atomic.

Proof:

• Focused tests: go test ./internal/cmd -run 'TestDocs(DeleteAtAnchorDryRunIncludesSelectors|MutatorsAtAnchorResolveRange|InsertPersonAtAnchorIsAtomic|AtAnchorLiteralWhitespace|AtAnchorPreservesHTMLEntities|AtAnchorRejectsSkippedInlineObjectSpan|AtAnchorRejectsPageBreakInTable|AtAnchorAmbiguousAndNoMatchDoNotMutate|AtAnchorValidation|FindRange)' -count=1
• make build
• Autoreview clean with make ci
• Live clawdbot smoke covered all five mutators plus readback/no-match/cleanup:
  • write_ok:true
  • insert_at_index:7
  • update_replaced:true
  • delete_deleted:13
  • person_replaced:true
  • page_at_index:62
  • read_insert_ok:true
  • read_update_ok:true
  • read_delete_ok:true
  • read_person_removed:true
  • missing_rc:3
  • cleanup_trashed:true
• Exact-head GitHub Actions: ci run 27165314491 success, pages run 27165314452 success.

Thanks @sebsnyk.