Problem

The Google Docs API exposes smart-chip insertion via documents().batchUpdate() with request types like insertPerson, insertRichLink, insertDate. gog docs doesn't expose any of these — there's no way to insert a smart chip from the CLI today.

Smart chips that would be useful at the CLI:

• Person chips — insertPerson with personProperties.email. Rendered with photo + email + presence; the right shape for reviewer tables and stakeholder lists.
• File chips — insertRichLink pointing at a Drive file. Rendered with the file icon + title.
• Date chips — insertDate. Rendered as a navigable date picker.
• Dropdown / Variable chips — not yet exposed in the Docs API (no insertDropdown / insertVariable request type as of 2026-05-22 — verified empirically). Would be useful for review-status columns where the user picks from a fixed set.

Verified API support today:

batchUpdate request types containing 'insert':
  - insertDate
  - insertInlineImage
  - insertPageBreak
  - insertPerson         <-- Person chip
  - insertRichLink       <-- File / event chip
  - insertSectionBreak
  - insertTable
  - insertTableColumn
  - insertTableRow
  - insertText

insertPerson works with:

{
  "insertPerson": {
    "location": {"index": <int>},
    "personProperties": {"email": "[email protected]"}
  }
}

Rendered element:

{
  "person": {
    "personId": "kix.<id>",
    "personProperties": {"name": "Display Name", "email": "[email protected]"}
  }
}

Proposed CLI surface

1. gog docs insert-person <docId> [email protected] [--at=INDEX|--at-end] [--tab=NAME] — single-call insertion of a Person chip.
2. gog docs insert-file-chip <docId> --file-id=<drive-id> [--at=INDEX] — insert a File chip (wraps insertRichLink).
3. gog docs insert-date-chip <docId> --date=YYYY-MM-DD [--at=INDEX] — insert a Date chip.
4. docs write --markdown promotion: when the converter encounters a [Name](mailto:email) link, promote it to a Person chip instead of rendering as a plain hyperlink. Optional --no-promote-mailto flag for users who want to keep mailto links as links.

Out of band — dropdown / variable chips

Dropdown chips exist in the Docs UI but have no insertDropdown / insertVariable request type in the API as of 2026-05-22. When the API surfaces dropdowns, this issue should be expanded to cover them with a gog docs insert-dropdown <docId> --options=... command.

Workaround in place today

Doc-publishing pipelines post-process via the Docs API directly — find mailto: link spans, deleteContentRange + insertPerson, in reverse order to avoid index shifts. Functional but per-pipeline overhead.

v0.18.0 verified

• No insert-person, insert-chip, or any chip-related subcommand on gog docs.
• No --promote-mailto / --smart-chips flag on docs write.