Motivation

The Docs API addresses every mutation by character index, but documents.get returns text spread across textRuns. Today, any script that wants to "do X to the literal text Y" must (1) call gog docs raw, (2) walk body.content concatenating textRuns, (3) compute start/end indices itself. Every consumer reinvents this walk, and gets the whitespace / HTML-entity edge cases wrong on the way.

Exposing a first-class find-range helper unblocks every other "by-text" mode (insert / delete / update / format etc.) and is also the foundation for resolving comment anchors.

Consumers

This is a load-bearing primitive. Direct consumers across the open enhancement set:

• feat(docs): add --at <text> anchor to insert / delete / update / insert-person / insert-page-break #683 --at <text> on insert / delete / update / insert-person / insert-page-break — reduces to a thin wrapper once find-range lands.
• feat(docs comments): add locate subcommand to resolve a comment to a body range #687 docs comments locate — find-range applied to a comment's quotedFileContent.value with whitespace + HTML-entity normalisation on.
• feat(docs write): pre-flight orphan-comment check on --replace --markdown #691 docs write --check-orphans — uses find-range (via feat(docs comments): add locate subcommand to resolve a comment to a body range #687) to test whether each comment's quote survives in the incoming body.
• feat(docs): top-level table-row / table-column / table-merge commands #686 top-level table-row / table-column / table-merge commands — the --table=<header-text> addressing mode is a sibling pattern (table walk by first-cell text), not a strict consumer, but benefits from the same edge-case handling once it exists.
• feat(docs): named-range create / list / delete / replace-content commands #692 docs named-range commands — the --at=<text> mode for named-range create depends on find-range.

Repro

Today, to delete a literal phrase a script has to do this:

gog docs raw <DOC_ID> -j \
  | jq -r '.body.content[] | .paragraph?.elements[]? | select(.textRun) | "\(.startIndex)\t\(.endIndex)\t\(.textRun.content)"' \
  | awk -F'\t' '\$3 ~ /\(PDF output also supported\)/' \
  | ... manual offset math ...
gog docs delete <DOC_ID> --start <START> --end <END>

Proposed surface

gog docs find-range <docId> <text> [flags]
  --match-case            Case-sensitive (default off)
  --all                   Return every occurrence (default: first only)
  --occurrence INT        Return the Nth occurrence (1-based)
  --normalize-whitespace  Collapse runs of whitespace in both haystack and needle (default on)
  --tab=STRING            Target a specific tab by title or ID

JSON output:

{
  "matches": [
    {"startIndex": 1234, "endIndex": 1267, "paragraphIndex": 12, "tabId": "kix.abc"}
  ]
}

Plain output: TSV startIndex<TAB>endIndex<TAB>paragraphIndex<TAB>tabId.

Behaviour notes:

• Normalises whitespace (collapses tabs / newlines / repeated spaces) before searching, but returns indices on the unnormalised body.
• HTML-entity-decodes the needle if it looks pre-encoded (", &, ', ·, >, <).
• Returns exit code 3 (matching --fail-empty convention) when no matches.

Acceptance criteria

• Single-occurrence and multi-occurrence (--all) modes both return correct indices verified against documents.get.
• Matches span across textRun boundaries inside the same paragraph (Docs splits runs on style boundaries; finder must not assume one run = one paragraph).
• Whitespace-normalised matches still report correct unnormalised indices.
• Works inside tab content with --tab= resolution.
• Returns empty matches array (not an error) when text not found, unless --fail-empty is set.

References

• documents.get: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get
• Document body shape (Paragraph / TextRun / startIndex semantics): https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#Body