draft-doc · diff

git:20261027.be0bbe9 to git:20261029.daff6b8

23 added, 27 removed. Audit A to A.

---
name: draft-doc
- description: "Create and update Google Docs with gws using native Drive Markdown (.md) and @2x Mermaid/SVG figures by default, or .gdoc when requested."
+ description: "Create and update Google Docs with gws: native Markdown with Mermaid/SVG figures, or styled .gdoc."
license: MIT
metadata:
kind: task
author: Médéric HURIER (Fmind)
source: github.com/fmind/dot/tree/main/skills/draft-doc
created: "2026-10-27"
- updated: "2026-10-27"
+ updated: "2026-10-29"
---
# Draft Doc
Create and update Google Docs deliverables in Google Drive with `gws`, following [stakeholder-writing](../stakeholder-writing/SKILL.md) ([outlines](../stakeholder-writing/references/outlines.md), [style](../stakeholder-writing/references/style.md), [checklist](../stakeholder-writing/references/checklist.md)). [gws](../gws/SKILL.md) owns authentication, Drive queries, and request mechanics.
## Format Choice
- 1. **Default — Native Drive Markdown (`.md`, `mimeType: text/markdown`)**: by default use `.md`, except if the user says to use `.gdoc` format. Native `.md` files open directly in Google Docs Editor (`https://docs.google.com/document/d/<FILE_ID>/edit`) with the left Document Outline, inline comments, suggestions, and revision history, and update atomically via `drive.files.update --upload` without `batchUpdate` UTF-16 index math.
- 1. **Exception — Converted Google Doc (`.gdoc`, `mimeType: application/vnd.google-apps.document`)**: use only when the user asks to use `.gdoc` format, or when a document requires multiple **Document Tabs** or Docs-native smart chips (`docs.documents.batchUpdate` is rejected on native `text/markdown` files).
-
- ## Branding (`~/.agents/DESIGN.md` or Customer Brand)
+ 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.
+ 1. **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](https://support.google.com/docs/answer/18289341)). Build it through [gws Docs recipes](../gws/references/services.md#docs).
- Style every SVG card and Mermaid diagram consistently (full token table and templates in [references/dialect.md](references/dialect.md#branding-and-mermaid-styling)):
+ ## Branding
- - **Default (`~/.agents/DESIGN.md` — Fmind Theme)**: use a light `#FFFFFF` canvas, `#F1F3F4` secondary panel, `#9AA0A6` structural border, `#202124` primary ink, `#595D62` muted caption text, `#174EA6` primary accent with `#D2E3FC` surface fill, semantic status pairs (Positive `#0D652D`/`#CEEAD6`, Warning `#934900`/`#FEEFC3`, Danger `#A50E0E`/`#FAD2CF`), and `Google Sans` / `Google Sans Code` typography.
- - **Customer branding (when available)**: apply the customer's palette (primary accent, light tint surface, text ink, neutral border), typography, and logo across all SVG `<style>` blocks and Mermaid frontmatter (`themeVariables` and `classDef` rules), keeping an opaque `#FFFFFF` canvas so figures stay legible in Google Docs light and dark modes. Ask for the customer's brand guide if missing; never invent colors or mix Fmind and customer brands in the same deliverable.
+ Style SVG cards and Mermaid diagrams with `~/.agents/DESIGN.md` (Fmind Theme) and the Mermaid frontmatter in [fmind-visuals renderers](../fmind-visuals/references/renderers.md#mermaid), 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.
- ## Google Docs `.md` Dialect Rules
+ ## Native `.md` Dialect Rules
- Google Docs parses native `.md` files with the rules detailed in [references/dialect.md](references/dialect.md) and validated by [`scripts/compile_markdown_doc.py`](scripts/compile_markdown_doc.py):
+ [references/dialect.md](references/dialect.md) records what Docs renders, verified live on 2026-10-28; [`scripts/compile_markdown_doc.py`](scripts/compile_markdown_doc.py) enforces these rules:
- 1. **No YAML frontmatter (`---`) or Setext underlines**: a closing `---` at the top of the file or `---` directly under a text line without a blank line triggers Setext `HEADING_2`. Place metadata lines (`Type:`, `Status:`, `Audience:`, `Author:`, `Date:`) below `# Title`, and always leave a blank line before a horizontal rule (`---`).
- 1. **No GitHub alerts (`> [!IMPORTANT]`)**: alert tokens render as literal text. Use a bold blockquote instead: `> **Important — Decision needed by YYYY-MM-DD:** ...`
- 1. **No raw HTML (`<details>`, `<summary>`, `<mark>`, `<u>`, `<br>`)**: HTML tags render as literal text. Put annexes under standard `## Annex` headings at the bottom of the file and use `\` for hard line breaks.
- 1. **Mermaid (`.mmd`) and SVG (`.svg`) figures compiled to `@2x` Base64 PNG references**: Google Docs renders fenced `mermaid` blocks as literal code and ignores `data:image/svg+xml` URIs. Author fenced ` ```mermaid ` blocks or link local 960px `.svg` cards (`![Caption](figure.svg)`) in `.src.md`, then run [`scripts/compile_markdown_doc.py`](scripts/compile_markdown_doc.py). The compiler replaces each figure with `![Caption][fig-N]`, appends `[fig-N]: <data:image/png;base64,...>` at the bottom of the `.md` file, and exports editable sources and `@2x` PNGs into `--assets-dir`.
- 1. **Supported natively**: `#`–`######` headings, bold/italic/strikethrough/inline code, inline and reference links, nested lists, interactive checklists (`- [ ]` / `- [x]`), GFM pipe tables, language-tagged fenced code blocks, LaTeX equations (`$...$` and `$$...$$`), and footnotes (`[^1]`).
+ 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.
+ 1. **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.
+ 1. **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.
+ 1. **Verified natively**: ATX headings, ordered lists, checklists, GFM tables, footnotes, `$...$` and `$$...$$` equations, and Base64 PNG reference images.
## Workflow
1. **Confirm account and destination**: check `gws auth status` without printing credentials, and resolve the target Drive folder ID or existing file ID with a bounded `gws drive files list` query.
- 1. **Author `.src.md` and `.svg` figures in `$SCRATCH`, then compile, validate, and upload to Google Drive** with [`scripts/compile_markdown_doc.py`](scripts/compile_markdown_doc.py):
+ 1. **Author `.src.md` and `.svg` figures in a scratch folder (`SCRATCH`: the host's scratchpad, else `SCRATCH="$(mktemp -d)"`), then compile, validate, and upload** with [`scripts/compile_markdown_doc.py`](scripts/compile_markdown_doc.py):
```bash
- # Compile .src.md -> .md, export editable assets, and upsert both <Title>.md and assets/<doc-slug>/ in Drive
+ # Create or upsert <Title>.md and assets/<doc-slug>/ in a Drive folder
uv run --no-project python ~/.agents/skills/draft-doc/scripts/compile_markdown_doc.py \
"$SCRATCH/report.src.md" -o "$SCRATCH/report.md" \
--drive-folder "<FOLDER_ID>" --doc-name "<Title>.md" --json
- # Update an existing .md document in place by File ID (preserves URL, revisions, and open Docs comments)
+ # Update an existing .md in place: keeps its name, URL, revisions, and assets/<slug of its Drive name>/
uv run --no-project python ~/.agents/skills/draft-doc/scripts/compile_markdown_doc.py \
"$SCRATCH/report.src.md" -o "$SCRATCH/report.md" \
- --file-id "<FILE_ID>" --drive-folder "<FOLDER_ID>" --json
+ --file-id "<FILE_ID>" --json
```
- To compile locally without uploading yet, omit `--drive-folder` and pass `--assets-dir "$SCRATCH/assets/<doc-slug>"`.
+ Add `--doc-name` to an update only to rename the document. To compile without uploading, omit the Drive flags and pass `--assets-dir "$SCRATCH/assets/<doc-slug>"`; `--check-only` validates without rendering.
- 1. **Verify by reading back**: confirm `inlineObjects` and heading structure via `gws docs documents get --params '{"documentId":"<FILE_ID>"}'`, and report both `drive.docs_url` (`https://docs.google.com/document/d/<FILE_ID>/edit`) and `drive.assets_folder_url` (`assets/<doc-slug>/`).
+ 1. **Verify by reading back**: `gws docs documents get --params '{"documentId":"<FILE_ID>","includeTabsContent":true}'` works on native `.md` files; confirm headings, `inlineObjects`, footnotes, and tables. Report `drive.docs_url` and `drive.assets_folder_url`.
## Gotchas
- - **Keep `mimeType: text/markdown` on upload**: setting `mimeType: application/vnd.google-apps.document` converts the file into a `.gdoc` and disables atomic Markdown updates.
- - **Never widen sharing without approval**: uploading or updating a file inherits its parent folder's permissions; ask the user before calling `drive.permissions.create`.
- - **Upload editable assets alongside figures**: always pass `--assets-dir` and sync the exported `.src.md`, `.mmd`, `.svg`, and `@2x` `.png` files to the Drive `assets/` folder so collaborators can edit diagrams without local workspace access.
+ - **Keep `mimeType: text/markdown` on upload**: `application/vnd.google-apps.document` converts the file into a `.gdoc`, which drops equations to literal `$...$` text.
+ - **Never widen sharing without approval**: uploads inherit the parent folder's permissions; ask before calling `drive.permissions.create`.
+ - **Download `.md` instead of exporting it**: `drive.files.export` rejects native `.md` files ("Export only supports Docs Editors files"); fetch the source with `drive.files.get` and `alt=media`.
## Documentation
- - [Google Developers Blog: Native Markdown in Docs and Drive](https://developers.googleblog.com/preview-edit-and-collaborate-on-markdown-md-files-natively-in-google-docs-and-drive/) · [Google Docs Help: Use Markdown](https://support.google.com/docs/answer/12014036) · [Google Workspace Updates: Markdown in Docs](https://workspaceupdates.googleblog.com/2024/07/import-and-export-markdown-in-google-docs.html) · [dialect and figure reference](references/dialect.md)
- - Companion skills: [stakeholder-writing](../stakeholder-writing/SKILL.md) (structure, prose, and reader check), [diagrams-as-code](../diagrams-as-code/SKILL.md) (Mermaid and SVG authoring), [gws](../gws/SKILL.md) (Workspace CLI and multi-tab `.gdoc` `batchUpdate`), [draft-mail](../draft-mail/SKILL.md) (Gmail drafts).
+ - [Docs Help: View and edit Markdown files in Google Docs](https://support.google.com/docs/answer/18289341) · [Workspace Updates, 2026-10-05: Markdown files natively across Drive and Docs](https://workspaceupdates.googleblog.com/2026/10/preview-edit-and-collaborate-on-Markdown-files-natively-across-Drive-and-Docs.html) · [dialect and figure reference](references/dialect.md)
+ - Companion skills: [stakeholder-writing](../stakeholder-writing/SKILL.md) (structure, prose, and reader check), [diagrams-as-code](../diagrams-as-code/SKILL.md) (Mermaid and SVG authoring), [gws](../gws/SKILL.md) (Workspace CLI and `.gdoc` `batchUpdate`), [draft-mail](../draft-mail/SKILL.md) (Gmail drafts).