docs write / page-layout: --margin-left, --margin-right, --margin-top, --margin-bottom

[sebsnyk]

Problem

No way to set page margins via the CLI today. After gog docs write --replace --markdown --pageless, margins stay at the default 72pt (1″) all around — too generous for pageless docs with wide tables.

Repro (v0.18.0)

gog docs write --help | grep -iE "margin|width"
# (no margin / width flags)

gog docs page-layout --help | grep -iE "margin"
# (no margin flags)

Proposed fix

Add --margin-left=<PT>, --margin-right=<PT>, --margin-top=<PT>, --margin-bottom=<PT> to docs write and docs page-layout. Accept either points or inches (--margin-left=0.5in).

Why it matters

Companion to #629 (pageSize widening). Both are needed for pageless docs with wide tables. Today users post-process via Docs API updateDocumentStyle — same call surface a CLI flag would wrap.

v0.18.0 verified

• No margin flags on docs write, docs update, or docs page-layout.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve.

Latest ClawSweeper review: 2026-05-22 12:22 UTC / May 22, 2026, 8:22 AM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

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.

Summary
Keep open: current main still lacks CLI margin controls for the Docs write and page-layout paths, so this remains a valid narrow feature request.

Reproducibility: yes. Source and generated docs show no margin flags on the relevant commands, and the shared style helper only updates documentFormat, so this is a high-confidence capability gap rather than a broken existing contract.

Next step
This is a narrow repair-lane feature candidate with clear files and tests, but it is not an automatic bug-fix because it adds new public CLI flags.

Review details

Best possible solution:

Add a shared Docs document-style margin parser/helper and expose the four explicit margin flags on docs write and docs page-layout, with focused tests and regenerated command docs.

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

Yes. Source and generated docs show no margin flags on the relevant commands, and the shared style helper only updates documentFormat, so this is a high-confidence capability gap rather than a broken existing contract.

Is this the best way to solve the issue?

Yes. The proposed four explicit flags are the narrowest maintainable shape; the implementation should update only supplied margin fields and leave page width behavior to the companion request at #629.

Label justifications:

• P2: This is a concrete user-facing CLI improvement with a clear implementation path and limited blast radius.

Acceptance criteria:

• go test ./internal/cmd
• make docs-commands
• make test

What I checked:

• Docs write has no margin flags: DocsWriteCmd exposes text/file/replace/markdown/append/pageless/tab/format fields, but no margin fields. (internal/cmd/docs_edit.go:35, f104579c7512)
• Docs page-layout has only layout selection: DocsPageLayoutCmd accepts docId and --layout; no margin options are present. (internal/cmd/docs_set_page_layout.go:21, f104579c7512)
• Current style helper updates only document mode: setDocumentMode sends UpdateDocumentStyle with DocumentFormat and Fields: "documentFormat", so margins are not written through this helper. (internal/cmd/docs_helpers.go:69, f104579c7512)
• Generated command docs omit margin flags: The generated docs write page lists --pageless but no margin controls, and docs page-layout lists only --layout among command-specific page style flags. (docs/commands/gog-docs-write.md:49, f104579c7512)
• No existing margin surface found: A source/docs search for the proposed flag names and Docs API margin field names returned no matches in the checkout. (f104579c7512)
• Feature history points to pageless/page-layout work: Blame and history tie the current pageless/page-layout implementation to the v0.18.0 release snapshot, with older Docs write/update work and later pageless support in the same area. (internal/cmd/docs_set_page_layout.go:13, 7c511d8dd731)

Likely related people:

• Peter Steinberger: Current Docs write/page-layout/helper lines blame to the v0.18.0 release commit, and history shows repeated Docs edit, pageless, page-layout, and helper work in this area. (role: recent area contributor; confidence: high; commits: 7c511d8dd731, f94860c9697b, b4d6f559c399; files: internal/cmd/docs_edit.go, internal/cmd/docs_helpers.go, internal/cmd/docs_set_page_layout.go)
• salmonumbrella: History for the central Docs edit files includes the original write/update command work and related file-input tests, making this a plausible adjacent routing candidate if maintainers want original command context. (role: original adjacent contributor; confidence: medium; commits: 44673ff1691f, feae67ba9d6c; files: internal/cmd/docs_edit.go, internal/cmd/docs_write_update_test.go)

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