draft-doc

Draft Doc

Create and update Google Docs deliverables in Google Drive with gws, following stakeholder-writing (outlines, style, checklist). gws owns authentication, Drive queries, and request mechanics.

Format Choice

1. Native Drive Markdown (.md, mimeType: text/markdown) for living docs: use it for agent-maintained, frequently updated, or working documents. It opens in the Docs editor (https://docs.google.com/document/d/<FILE_ID>/edit) without conversion and updates in place with drive.files.update --upload, without batchUpdate index math.
2. Converted Google Doc (.gdoc, mimeType: application/vnd.google-apps.document) for polished deliverables: use it for client or stakeholder documents that need styling, and for multi-tab documents. Editing a .md file in Docs turns smart chips into text or links and removes font colors, highlights, and text alignment (Docs Help 18289341). Build it through gws Docs recipes.

Branding

Style SVG cards and Mermaid diagrams with ~/.agents/DESIGN.md (Fmind Theme) and the Mermaid frontmatter in fmind-visuals renderers, or with the customer's brand guide when the deliverable is theirs. Ask for a missing guide; never invent customer colors or mix brands. Keep an opaque white canvas so figures stay legible in dark mode.

Native .md Dialect Rules

references/dialect.md records what Docs renders, verified live on 2026-10-28; scripts/compile_markdown_doc.py enforces these rules:

1. No YAML frontmatter or Setext underlines: --- or === directly under a paragraph line makes it a heading. Put metadata lines below # Title and leave a blank line before a horizontal rule.
2. No GitHub alerts, raw HTML, or HTML comments: they render as literal text. Use a bold blockquote (> **Important — Decision needed by YYYY-MM-DD:** ...), ## Annex headings, and \ for hard line breaks.
3. Compile figures to PNG references: Docs shows fenced mermaid blocks as code. Author fenced mermaid blocks or local ![Caption](figure.svg) links to 600 px wide SVGs in .src.md; the compiler renders each one to a PNG at most 600 px wide, because Docs displays PNG pixels at 0.75 pt each and ignores DPI metadata. It then writes ![Caption][fig-N] in the body, appends [fig-N]: <data:image/png;base64,...> definitions, and exports editable sources to --assets-dir. Mermaid runs through a pinned mise exec Mermaid CLI, so no global install is needed.
4. Verified natively: ATX headings, ordered lists, checklists, GFM tables, footnotes, $...$ and $$...$$ equations, and Base64 PNG reference images.