docs: surface headingId (and bookmark/named-range anchors) in headings/paragraphs output for deep-linking

[sebsnyk]

Problem

The Google Docs API exposes each heading paragraph's auto-generated anchor id at paragraph.paragraphStyle.headingId — this is exactly what ...#heading=h.xxxx deep links resolve to. But gog docs headings list and gog docs paragraphs list (both -p and --json) omit it. Without it there is no way to build a deep link to a specific heading from gog output alone; you have to drop down to a raw Docs API client (documents.get(includeTabsContent=true)) just to read a field gog already has in hand.

Request

Surface headingId in:

• gog docs headings list — per-heading object (at minimum in --json)
• gog docs paragraphs list — per-paragraph object, when the paragraph carries one

Adjacent (same deep-linking use case)

The same "I have the element but cannot link to it" gap applies to the other anchorable targets the API already returns. Worth covering in one pass:

• bookmark ids (bookmark / bookmarkId on a paragraph or text run) — for #bookmark=id links
• named ranges (document.namedRanges)

Surfacing these lets a caller build any in-document deep link without a second API client.

Repro

gog docs headings list <docId> --json
# each heading object has index/start/end/style/text but no headingId

Version

gog 0.27.1

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 15, 2026, 4:46 PM ET / 20:46 UTC.

Summary
Keep open: current main and the latest release still omit paragraph-style headingId from headings and paragraphs JSON, and the linked implementation PR should remain the owner until it merges.

Reproducibility: yes. Source inspection shows current main does not carry ParagraphStyle.HeadingId into either headings or paragraphs JSON output; live Google Docs execution was not needed to verify the source omission.

Next step
An open linked implementation PR already owns the fix, so no separate repair lane should start.

Review details

Best possible solution:

Land #820 if maintainers accept the JSON output contract, then close this issue once headingId is present on main.

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

Yes. Source inspection shows current main does not carry ParagraphStyle.HeadingId into either headings or paragraphs JSON output; live Google Docs execution was not needed to verify the source omission.

Is this the best way to solve the issue?

Yes for the central headingId gap. The linked PR carries the existing Docs API field into JSON while preserving TSV/plain output; named ranges should stay on the existing named-range command unless maintainers choose a broader contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The adjacent bookmark and named-range scope is partly covered by existing text-run link metadata and docs named-range list, so a fix should avoid creating duplicate or conflicting output contracts.
• The issue should not close before fix(docs): expose heading IDs in enumerator JSON #820 merges because current main and v0.27.1 still show the missing headingId path.

Codex review notes: model internal, reasoning high; reviewed against 02c893f2e702.

Label changes

Label changes:

• add P2: This is a bounded improvement to an existing Docs command surface with limited blast radius.
• add impact:other: The issue affects scriptable in-document deep-link generation from gog's Docs output.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded improvement to an existing Docs command surface with limited blast radius.
• impact:other: The issue affects scriptable in-document deep-link generation from gog's Docs output.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was fully read; its parseable stdout guidance applies because the request changes CLI JSON/plain output shape. (AGENTS.md:18, 02c893f2e702)
• Vision fit: VISION.md supports small useful primitives in already supported Google Workspace areas and stable scriptable output, which fits a JSON metadata addition to existing Docs commands. (VISION.md:5, 02c893f2e702)
• Current output structs omit headingId: docsParagraphListItem and docsParagraphInspectItem expose index/start/end/style/text fields but no paragraph-level headingId. (internal/cmd/docs_enumerators.go:72, 02c893f2e702)
• Current enumerator does not carry ParagraphStyle.HeadingId: enumerateDocsParagraphs reads ParagraphStyle.NamedStyleType but does not copy ParagraphStyle.HeadingId, so the value cannot reach headings or paragraphs JSON on main. (internal/cmd/docs_enumerators.go:507, 02c893f2e702)
• Adjacent bookmark and heading link metadata already exists for text runs: Text-run link output already has bookmarkId and headingId, covering linked runs but not the paragraph heading anchor requested here. (internal/cmd/docs_enumerators.go:101, 02c893f2e702)
• Named range anchor surface already exists: docs named-range list emits named range IDs and spans through the dedicated named-range command surface. (internal/cmd/docs_named_ranges.go:58, 02c893f2e702)

Likely related people:

• Peter Steinberger: Blame and log history show Peter authored the Docs content enumerator, named-range command surface, paragraph-run metadata, and the current v0.27.1 enumerator files. (role: feature-history owner; confidence: high; commits: e51f6be9dc38, b34e3033913a, 22c97dea8707; files: internal/cmd/docs_enumerators.go, internal/cmd/docs_enumerators_test.go, internal/cmd/docs_named_ranges.go)
• Sebastian Roth: Sebastian reported this deep-linking workflow and has recent merged Docs command work, including tab-aware markdown and table-cell updates, which makes them useful workflow context. (role: adjacent Docs contributor; confidence: medium; commits: f0dbde21f892, 58b866e9ac55, b646e886f6dd; files: internal/cmd/docs_mutation.go, internal/cmd/docs_table_inserter.go, 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.

[clawsweeper]

🦞✅
Implementation PR opened: #820
Status: The implementation PR is open. Post-flight status: checks are not clean: test: IN_PROGRESS, windows: IN_PROGRESS
Worker: https://github.com/openclaw/clawsweeper/actions/runs/27555998189