feat(docs): named-range create / list / delete / replace-content commands

[sebsnyk]

Motivation

Named ranges are the API-native way to maintain a stable anchor inside a doc even as text around it changes. They survive edits to surrounding paragraphs in a way that "find text and compute index" does not. For round-trip workflows (a script writes content, later wants to update just one section), named ranges are the durable solution; text-based locate is a fallback.

The Docs API supports CreateNamedRange, DeleteNamedRange, and ReplaceNamedRangeContent. gog already emits CreateNamedRange via the sed bookmark brace ({B=name} in internal/cmd/docs_sed_brace_structural.go), and DeleteNamedRange is exposed in the sheets path (internal/cmd/sheets_named_ranges.go), but neither is reachable as a top-level docs subcommand. ReplaceNamedRangeContent is not emitted anywhere.

Depends on

• feat(docs): add find-range primitive that maps text to Document index ranges #682 find-range primitive — only for the --at=<text> mode of named-range create. The --start=N --end=N mode is independent. If feat(docs): add find-range primitive that maps text to Document index ranges #682 has not landed yet, this issue can ship with index-only addressing and gain --at=<text> later as a non-breaking addition.

Repro

# Today: no way to create a stable anchor; every update is "walk docs raw, find the text".

# Wanted:
gog docs named-range create <DOC_ID> --name=intro-paragraph --at="The introduction begins here."
# Later, regardless of edits above:
gog docs named-range replace <DOC_ID> --name=intro-paragraph --content="<markdown>"

Proposed surface

gog docs named-range create <docId> --name=<id> --at=<text>|--start=N --end=N
gog docs named-range list <docId> [--name=<id>]
gog docs named-range delete <docId> --name=<id>
gog docs named-range replace <docId> --name=<id> --content=<text> [--format=plain|markdown]

Acceptance criteria

• Create wires to CreateNamedRange with the resolved range; returns the namedRangeId.
• Delete uses DeleteNamedRange (new request type for the docs side).
• Replace uses ReplaceNamedRangeContent (preferred) or DeleteContentRange + InsertText fallback when the named range covers complex content.
• List returns the doc's namedRanges from documents.get.

References

• CreateNamedRangeRequest / DeleteNamedRangeRequest: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request
• ReplaceNamedRangeContentRequest: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request#ReplaceNamedRangeContentRequest
• Document.namedRanges field: https://developers.google.com/workspace/docs/api/reference/rest/v1/documents#Document

[clawsweeper]

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

Summary
Keep open: current main has adjacent Docs named-range internals and Sheets named-range commands, but it still does not expose the requested top-level Docs named-range create/list/delete/replace command group.

Reproducibility: yes. from source inspection: DocsCmd has no named-range command group while the issue requests a new Docs command surface. This is a feature gap rather than a broken existing command.

Next step
Maintainer/product review should decide the new Docs named-range command contract and whether it should wait for the open find-range primitive.

Review details

Best possible solution:

Keep this open until maintainers choose the Docs named-range command contract, then implement create/list/delete/replace with parseable output, focused unit tests, generated command docs, and live Google Docs proof.

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

Yes from source inspection: DocsCmd has no named-range command group while the issue requests a new Docs command surface. This is a feature gap rather than a broken existing command.

Is this the best way to solve the issue?

Unclear until maintainers choose the product shape: the proposed surface is coherent, but VISION.md puts new API surfaces in the discuss-first bucket and the issue is already labeled for product review.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The --at=<text> create mode depends on the open find-range primitive at feat(docs): add find-range primitive that maps text to Document index ranges #682, while the index-based mode could be implemented independently.
• Replace semantics need maintainer direction for complex named ranges where ReplaceNamedRangeContent may not be enough and a delete/insert fallback could change content structure.

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

Label changes

Label changes:

• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.
• remove issue-rating: 🌊 off-meta tidepool: Current issue advisory state no longer selects this label.

Label justifications:

• P2: This is a normal-priority feature request for a supported Docs area with limited blast radius.
• impact:other: The missing surface affects durable Docs automation anchors, which is maintainer-visible but outside the specific owned impact categories.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its guidance to keep stdout parseable and test changes next to code applies to any eventual command implementation. (AGENTS.md:1, 3d5c9cef65fa)
• Vision fit: VISION.md says small useful primitives in supported Google Workspace areas fit, but new API surfaces should be discussed first. (VISION.md:1, 3d5c9cef65fa)
• Docs command surface missing requested group: DocsCmd lists the current top-level docs commands and has no named-range or named-ranges command group. (internal/cmd/docs.go:20, 3d5c9cef65fa)
• Adjacent Docs create support is internal to sed bookmarks: The Docs sed structural helper emits CreateNamedRangeRequest for brace bookmarks, but this is not a standalone create/list/delete/replace command surface. (internal/cmd/docs_sed_brace_structural.go:105, 3d5c9cef65fa)
• No Docs replace/delete named-range command implementation found: The targeted search found Sheets named-range docs and the Docs sed CreateNamedRange helper, but no Docs ReplaceNamedRangeContent or Docs named-range command implementation. (internal/cmd/docs_sed_brace_structural.go:114, 3d5c9cef65fa)
• Sheets analogue exists separately: Sheets already exposes sheets named-ranges, confirming the named-range management surface exists for Sheets but not Docs. (internal/cmd/sheets.go:51, 3d5c9cef65fa)

Likely related people:

• Vinston: Introduced the sed-style Docs formatting DSL and buildBookmarkRequest, which emits CreateNamedRange for brace bookmarks. (role: introduced adjacent Docs behavior; confidence: high; commits: e2d41ad87c56, 2853ff564ee3; files: internal/cmd/docs_sed_brace_structural.go, internal/cmd/docs_sed_brace_structural_test.go)
• Alex Naidis: Added the Sheets named-range command implementation that is the closest existing command-surface analogue. (role: introduced adjacent Sheets named-range behavior; confidence: medium; commits: 1da21969a825; files: internal/cmd/sheets_named_ranges.go, internal/cmd/sheets.go)
• Peter Steinberger: Hardened the Sheets named-range path and the release commit currently blames the relevant command files in this checkout's shallow history. (role: recent adjacent hardening and release owner; confidence: medium; commits: 3c696c987d7d, 2c84d8981dd5; files: internal/cmd/sheets_named_ranges.go, internal/cmd/docs.go, internal/cmd/docs_sed_brace_structural.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.