gog docs insert: default --index to end-of-doc (or rename / require it explicit)

[chrischall]

Summary

gog docs insert --index defaults to 1 (beginning of doc), which produces reversed output on sequential inserts. The help text says Character index to insert at (1 = beginning) — accurate, but counterintuitive to anyone reading "insert" as "add to the end" (the editor-style default).

Current behavior

docId=$(gog docs create test --json | jq -r '.id')
gog docs insert $docId 'FIRST\n'
gog docs insert $docId 'SECOND\n'
gog docs insert $docId 'THIRD\n'
gog docs cat $docId
# THIRD
# SECOND
# FIRST

All three responses return {atIndex: 1, ...}. Expected: FIRST\nSECOND\nTHIRD.

Why this matters

For iterative document construction — the dominant agent use case (build a long doc in chunks across many tool calls) — this silently produces a broken document. The agent has no way to detect the failure mid-stream; only the human notices when they open the doc.

Proposed fixes (any one of)

1. Default --index to endIndex - 1 of the body when omitted. Closest to "what insert should do" in editors.
2. Use endOfSegmentLocation for the API request when no --index is supplied. Cleanest at the API layer.
3. Make --index required, no default. Forces explicit choice.
4. Add --at-end flag, keep current default. Least disruptive but adds surface area.

I'd argue (1) or (2). (1) matches what users expect from insert in any text editor. The current default of 1 may have been Docs-API parity (Location.index = 1), but gog is a higher-level CLI and should optimize for human/agent UX over raw API mirroring.

Workaround in the MCP wrapper

I worked around this by adding a separate gog_docs_append tool that calls gog docs write --append — see chrischall/gogcli-mcp#8 (now closed in our repo). gog docs write --append already does the right thing, which suggests the "default to end" intuition is the consistent one.

---

Filed by Claude (AI agent) on behalf of @chrischall while expanding gogcli-mcp — an MCP wrapper around gogcli — to cover more of the upstream surface. The use case is real; please treat as a normal feature request.