From 11c27094725c116714069496d95dfb07a0ae2d54 Mon Sep 17 00:00:00 2001 From: Sripathi Krishnan Date: Mon, 13 Apr 2026 12:37:06 +0530 Subject: [PATCH 1/4] =?UTF-8?q?client:=20improve=20docs=20AX=20=E2=80=94?= =?UTF-8?q?=20clean=20up=20help=20text=20for=20markdown-first=20workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix top-level help: label docs as "markdown" (not XML), simplify workflow comment - Fix docs module help: correct command names (doc→docs), remove XML advertisement, add "open index.md first" orientation hint - Fix docs pull help: document .extrasuite/ as internal (do not edit), fix output_dir default claim, add comments.xml edit guidance - Fix docs push help: name .extrasuite/pristine.zip explicitly instead of "internal snapshot", clarify --verify flag purpose - Rewrite troubleshooting reference: replace XML-focused content with markdown-relevant errors and a diagnostic checklist - Hide pull-xml, push-xml, pull-md, push-md from docs subcommand listing; commands remain functional but no longer appear in --help output. Works around Python 3.13 argparse not honouring SUPPRESS for subparsers. Co-Authored-By: Claude Sonnet 4.6 --- client/src/extrasuite/client/cli/__init__.py | 16 ++- client/src/extrasuite/client/help/README.md | 8 +- .../src/extrasuite/client/help/doc/README.md | 12 +- client/src/extrasuite/client/help/doc/pull.md | 17 ++- client/src/extrasuite/client/help/doc/push.md | 13 ++- .../client/help/doc/troubleshooting.md | 107 +++++++----------- 6 files changed, 79 insertions(+), 94 deletions(-) diff --git a/client/src/extrasuite/client/cli/__init__.py b/client/src/extrasuite/client/cli/__init__.py index 056115e7..2e7599e7 100644 --- a/client/src/extrasuite/client/cli/__init__.py +++ b/client/src/extrasuite/client/cli/__init__.py @@ -691,10 +691,10 @@ def build_parser() -> Any: help="Permission role (default: reader)", ) - # XML format variants + # XML format variants — hidden from help, still functional sp = doc_sub.add_parser( "pull-xml", - help="Download document as XML", + help=argparse.SUPPRESS, parents=[auth_parent], description=_load_help("docs", "pull-xml"), formatter_class=argparse.RawDescriptionHelpFormatter, @@ -704,7 +704,7 @@ def build_parser() -> Any: sp = doc_sub.add_parser( "push-xml", - help="Push XML changes to Google Docs", + help=argparse.SUPPRESS, parents=[auth_parent], description=_load_help("docs", "push"), formatter_class=argparse.RawDescriptionHelpFormatter, @@ -767,7 +767,7 @@ def build_parser() -> Any: # Legacy aliases (hidden from help but still functional) for alias in ("pull-md", "push-md"): - sp = doc_sub.add_parser(alias, parents=[auth_parent]) + sp = doc_sub.add_parser(alias, help=argparse.SUPPRESS, parents=[auth_parent]) if "pull" in alias: sp.add_argument("url", help="Document URL or ID") sp.add_argument("output_dir", nargs="?", help="Output directory") @@ -784,6 +784,14 @@ def build_parser() -> Any: ) sp.add_argument("topic_parts", nargs="*", help="Topic path (omit to list all)") + # Python 3.13 always appends to _choices_actions even for SUPPRESS; prune manually. + # Also set metavar so the usage line only shows visible commands. + _HIDDEN_DOC_CMDS = frozenset({"pull-xml", "push-xml", "pull-md", "push-md"}) + doc_sub._choices_actions = [ + a for a in doc_sub._choices_actions if a.dest not in _HIDDEN_DOC_CMDS + ] + doc_sub.metavar = "{" + ",".join(a.dest for a in doc_sub._choices_actions) + "}" + # --- gmail --- gmail_parser = subparsers.add_parser( "gmail", diff --git a/client/src/extrasuite/client/help/README.md b/client/src/extrasuite/client/help/README.md index bbe677f1..2fdb5abe 100644 --- a/client/src/extrasuite/client/help/README.md +++ b/client/src/extrasuite/client/help/README.md @@ -4,7 +4,7 @@ ExtraSuite - edit Google Workspace files with AI agents using a local pull-edit- sheets Google Sheets (spreadsheets, formulas, charts) slides Google Slides (presentations, SML markup) - docs Google Docs (documents, XML markup) + docs Google Docs (documents, markdown) forms Google Forms (surveys, quizzes) script Google Apps Script (standalone and bound scripts) gmail Gmail (compose drafts, read and reply to emails) @@ -14,9 +14,9 @@ ExtraSuite - edit Google Workspace files with AI agents using a local pull-edit- ## Core Workflow (sheets, slides, docs, forms, script) - extrasuite pull [output_dir] # Convert google workspace file to local files inside / - # Edit files inside / - extrasuite push # Identify changes made and apply them to the google workspace file + extrasuite pull [output_dir] # Download to a local folder + # Edit the local files + extrasuite push # Apply changes to Google Make all changes locally and push once when done. Always re-pull before making further changes. diff --git a/client/src/extrasuite/client/help/doc/README.md b/client/src/extrasuite/client/help/doc/README.md index 6843a707..702512e3 100644 --- a/client/src/extrasuite/client/help/doc/README.md +++ b/client/src/extrasuite/client/help/doc/README.md @@ -2,11 +2,11 @@ Google Docs - edit documents using GitHub-flavored markdown. pull downloads one markdown file per tab. Edit them, then push to sync back. - extrasuite doc pull [output_dir] Download document as markdown - extrasuite doc push Push local changes to Google Docs - extrasuite doc create Create a new document - extrasuite doc share <url> <emails> Share with contacts + extrasuite docs pull <url> [output_dir] Download document as markdown + extrasuite docs push <folder> Push local changes to Google Docs + extrasuite docs create <title> Create a new document + extrasuite docs share <url> <emails> Share with contacts -Always re-pull after pushing before making more changes. +After pull, open index.md to orient yourself, then edit files in tabs/. -For XML format: use pull-xml / push-xml instead. +Always re-pull after pushing before making more changes. diff --git a/client/src/extrasuite/client/help/doc/pull.md b/client/src/extrasuite/client/help/doc/pull.md index 93c6f1c8..0cbe7168 100644 --- a/client/src/extrasuite/client/help/doc/pull.md +++ b/client/src/extrasuite/client/help/doc/pull.md @@ -2,22 +2,29 @@ Download a Google Doc as a folder of markdown files. ## Usage - extrasuite doc pull <url> [output_dir] + extrasuite docs pull <url> [output_dir] ## Arguments url Document URL or ID - output_dir Output directory (optional, defaults to <document_id>/) + output_dir Output directory (optional, defaults to current directory) ## Output index.md Table of contents with line numbers (read-only, start here) tabs/<Name>.md One markdown file per tab (edit these) - comments.xml Comments and replies + comments.xml Comments and replies (editable — see below) + .extrasuite/ Internal snapshot used by push — do not edit Each tab file uses standard GitHub-flavored markdown with YAML frontmatter for tab identity (id, title). Do not remove the frontmatter. +## Comments + +comments.xml is pre-populated with existing comments. To add a reply or +resolve a comment, edit the file directly. Run `extrasuite docs help comments-reference` +for the format. + ## Adding a New Tab Create a new .md file in the tabs/ directory. The title is derived from the @@ -25,5 +32,5 @@ filename (underscores become spaces). Push will create the tab in Google Docs. ## Example - extrasuite doc pull https://docs.google.com/document/d/abc123 - extrasuite doc pull https://docs.google.com/document/d/abc123 ./my-doc + extrasuite docs pull https://docs.google.com/document/d/abc123 + extrasuite docs pull https://docs.google.com/document/d/abc123 ./my-doc diff --git a/client/src/extrasuite/client/help/doc/push.md b/client/src/extrasuite/client/help/doc/push.md index 8f4a8aef..10855796 100644 --- a/client/src/extrasuite/client/help/doc/push.md +++ b/client/src/extrasuite/client/help/doc/push.md @@ -2,7 +2,7 @@ Push local changes to Google Docs. ## Usage - extrasuite doc push <folder> + extrasuite docs push <folder> ## Arguments @@ -11,12 +11,13 @@ Push local changes to Google Docs. ## Flags -f, --force Push despite validation warnings - --verify Re-pull after push to verify changes were applied correctly + --verify Re-pull after push and confirm changes were applied correctly ## Important -Always re-pull before making more changes. The internal snapshot is not -auto-updated, so subsequent pushes without re-pulling generate incorrect diffs. +Always re-pull before making more changes. Push compares current files against +.extrasuite/pristine.zip — this snapshot is not updated after push, so a second +push without re-pulling will generate an incorrect diff. - extrasuite doc push ./my-doc - extrasuite doc pull <url> ./my-doc + extrasuite docs push ./my-doc + extrasuite docs pull <url> ./my-doc # always re-pull before editing further diff --git a/client/src/extrasuite/client/help/doc/troubleshooting.md b/client/src/extrasuite/client/help/doc/troubleshooting.md index ad6aa9c4..da664a6c 100644 --- a/client/src/extrasuite/client/help/doc/troubleshooting.md +++ b/client/src/extrasuite/client/help/doc/troubleshooting.md @@ -7,82 +7,62 @@ Common issues and fixes for extradoc push. ### "Changes not applied after push" Always re-pull after push before making more edits: - extrasuite doc push <folder> - extrasuite doc pull <url> <folder> + extrasuite docs push <folder> + extrasuite docs pull <url> <folder> ### Push produces unexpected results -The .pristine/ state is stale. Re-pull to get a fresh copy: - extrasuite doc pull <url> <folder> +The .extrasuite/pristine.zip snapshot is stale. Re-pull to get a fresh copy: + extrasuite docs pull <url> <folder> # Make your edits again on the fresh copy - extrasuite doc push <folder> - -### "Horizontal rule count changed" error - -You added or removed an <hr/> element. The Google Docs API cannot add or -remove horizontal rules. Revert any <hr/> changes. - -### Push fails on table changes - -Most common causes: -- Missing <p> inside a <td>: every cell needs at least one <p>, even if empty -- Removed a physical <td> for a merged cell: colspan/rowspan are visual metadata - only - all physical <td> elements must remain in the XML + extrasuite docs push <folder> ### Heading after a list becomes a list item If you place a heading directly after a list with no separator, Google Docs absorbs the heading into the list and strips its heading style: -```xml -<!-- Wrong: heading is absorbed as a numbered list item --> -<li type="decimal" level="0">Last item</li> -<h2>Next Section</h2> +```markdown +<!-- Wrong --> +- Last item +## Next Section + +<!-- Correct: blank line creates a paragraph break --> +- Last item -<!-- Correct: empty paragraph breaks the list context --> -<li type="decimal" level="0">Last item</li> -<p></p> -<h2>Next Section</h2> +## Next Section ``` -This applies after both bullet and numbered lists. The push succeeds silently — +This applies after both bullet and numbered lists. Push succeeds silently — re-pull to verify headings rendered correctly. -### Style changes not applying +### Horizontal rule cannot be added or removed -1. Verify the class ID in document.xml matches an id in styles.xml -2. Verify the style has the correct properties defined -3. For new styles: add the <style> element to styles.xml first - ---- - -## API Limitations +The Google Docs API does not support inserting or deleting horizontal rules. +Revert any `---` additions or removals. -Cannot add or remove: <hr/>, <image/>, <autotext/>, <columnbreak/> +### New tab header/footer not appearing -Also note: -- <sectionbreak/> is required and read-only -- TOC / opaque pulled-only blocks are read-only -- New-tab header/footer creation in an existing multi-tab doc is not supported; - create the tab first, re-pull, then add header/footer - -Everything else in the supported tags list is editable. +Creating a header/footer for a new tab in an existing multi-tab doc is not +supported in the same push. Create the tab first, re-pull, then add the +header/footer. --- -## Table Cell Structure +## API Limitations + +Cannot add or remove via push: +- Horizontal rules (`---`) +- Images +- Auto-text fields (page numbers, date, etc.) +- Column breaks -Each row must have the same number of <td> elements regardless of merging. -colspan/rowspan are visual-only - merged cells still exist as physical <td> elements. +Also read-only: +- Section breaks +- Table of contents blocks +- Opaque "pulled-only" blocks -Example: 3-column table where first cell spans 2 columns: -```xml -<tr id="row1"> - <td id="c1" colspan="2"><p>Merged cell (columns 1-2)</p></td> - <td id="c2"><p></p></td> <!-- Physical cell covered by merge - required --> - <td id="c3"><p>Column 3</p></td> -</tr> -``` +Everything else in the supported markdown and frontmatter is editable. --- @@ -90,19 +70,8 @@ Example: 3-column table where first cell spans 2 columns: When push doesn't work as expected: -1. Did you re-pull before editing? (stale pristine is the #1 cause) -2. Is the XML valid? Check for unescaped & < > " characters -3. Does every <td> contain a <p>? (even empty cells) -4. Are all physical table cells present? (even merged ones) -5. Did you add/remove an <hr/>? (not supported) -6. Does your class reference a style defined in styles.xml? -7. Run diff to preview what will be pushed: extrasuite doc diff <folder> - ---- - -## XML Escaping - - & → & - < → < - > → > (optional but recommended) - " → " (only in attributes) +1. Did you re-pull before editing? (stale .extrasuite/pristine.zip is the #1 cause) +2. Does every table cell have content? (empty cells need at least a blank line) +3. Did you add or remove a horizontal rule `---`? (not supported) +4. Did you modify YAML frontmatter in a tab file? (id and title fields are read-only) +5. Use --verify to auto-confirm: extrasuite docs push --verify <folder> From 7809bdaa463a702b8ca308f6365a90c3416383f4 Mon Sep 17 00:00:00 2001 From: Sripathi Krishnan <Sripathi.Krishnan@gmail.com> Date: Mon, 13 Apr 2026 13:07:14 +0530 Subject: [PATCH 2/4] =?UTF-8?q?client:=20fix=20docs=20pull=20help=20?= =?UTF-8?q?=E2=80=94=20correct=20default=20dir,=20expand=20markdown=20guid?= =?UTF-8?q?e,=20hide=20stale=20refs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pull.md: fix default output_dir (was "current directory", is actually <document_id>/ in CWD) - pull.md: rewrite as a working guide — index.md orientation, line numbers, new-tab frontmatter snippet, full GFM feature list with callout syntax, images caveat, read-only elements - _common.py: hide troubleshooting, pull-xml, style-reference from `docs help` listing (XML-era content, not relevant to markdown workflow) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --- client/src/extrasuite/client/cli/_common.py | 3 ++ client/src/extrasuite/client/help/doc/pull.md | 41 +++++++++++++++---- 2 files changed, 36 insertions(+), 8 deletions(-) diff --git a/client/src/extrasuite/client/cli/_common.py b/client/src/extrasuite/client/cli/_common.py index 39e3e9ac..437d8c9d 100644 --- a/client/src/extrasuite/client/cli/_common.py +++ b/client/src/extrasuite/client/cli/_common.py @@ -33,6 +33,9 @@ "create.md", "batchupdate.md", "lint.md", + "troubleshooting.md", # stale XML-era content; hidden until rewritten + "pull-xml.md", # XML workflow reference; not advertised for markdown path + "style-reference.md", # XML-only (styles.xml / document.xml); hidden for markdown path } ) diff --git a/client/src/extrasuite/client/help/doc/pull.md b/client/src/extrasuite/client/help/doc/pull.md index 0cbe7168..8c0ad512 100644 --- a/client/src/extrasuite/client/help/doc/pull.md +++ b/client/src/extrasuite/client/help/doc/pull.md @@ -7,7 +7,7 @@ Download a Google Doc as a folder of markdown files. ## Arguments url Document URL or ID - output_dir Output directory (optional, defaults to current directory) + output_dir Output directory (optional, defaults to <document_id>/ in CWD) ## Output @@ -16,8 +16,38 @@ Download a Google Doc as a folder of markdown files. comments.xml Comments and replies (editable — see below) .extrasuite/ Internal snapshot used by push — do not edit -Each tab file uses standard GitHub-flavored markdown with YAML frontmatter -for tab identity (id, title). Do not remove the frontmatter. +## Working with the files + +**index.md** lists every heading in every tab with its line number. Use it to +orient yourself and jump to the exact line you want to edit. + +**tabs/*.md** are the editable files. Each begins with YAML frontmatter (id, +title) — do not remove it. + +**New tabs**: create a new .md file in tabs/ with frontmatter. The filename +becomes the tab title (underscores become spaces). Push creates the tab. + + --- + id: "" + title: My New Tab + --- + +## Markdown features + +Standard GFM is supported: headings, bold, italic, strikethrough, `inline code`, +fenced code blocks, bullet/numbered/checkbox lists, pipe tables, and links. +Links to headings in the same doc use `[text](#Heading Name)` or +`[text](#Tab_Name/Heading Name)` for cross-tab. + +Blockquotes and callouts are supported: + > regular blockquote + > [!NOTE], [!WARNING], [!INFO], [!DANGER], [!TIP] + +Images are shown as `![alt](uri)`. The URI is a Google-hosted URL — you can +change the alt text but cannot insert new images via push. + +Horizontal rules, footnotes, section breaks, and TOC blocks are pulled as-is +and are read-only. ## Comments @@ -25,11 +55,6 @@ comments.xml is pre-populated with existing comments. To add a reply or resolve a comment, edit the file directly. Run `extrasuite docs help comments-reference` for the format. -## Adding a New Tab - -Create a new .md file in the tabs/ directory. The title is derived from the -filename (underscores become spaces). Push will create the tab in Google Docs. - ## Example extrasuite docs pull https://docs.google.com/document/d/abc123 From 1156006ae831033a40f237e9f2c49a9e266b4766 Mon Sep 17 00:00:00 2001 From: Sripathi Krishnan <Sripathi.Krishnan@gmail.com> Date: Mon, 13 Apr 2026 13:27:42 +0530 Subject: [PATCH 3/4] client: consolidate docs editing guide into module --help Move all editing knowledge into docs README.md so agents don't need to cascade to pull --help on the happy path. One paragraph covers: index.md as the map with line numbers, editing tabs/*.md, creating tabs with frontmatter, supported GFM features, callout syntax, heading links, images read-only caveat, and re-pull reminder. Trim pull.md to a minimal flags reference (url, output_dir, --no-raw). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --- .../src/extrasuite/client/help/doc/README.md | 15 +++-- client/src/extrasuite/client/help/doc/pull.md | 57 +------------------ 2 files changed, 12 insertions(+), 60 deletions(-) diff --git a/client/src/extrasuite/client/help/doc/README.md b/client/src/extrasuite/client/help/doc/README.md index 702512e3..6b1f1c9d 100644 --- a/client/src/extrasuite/client/help/doc/README.md +++ b/client/src/extrasuite/client/help/doc/README.md @@ -1,12 +1,17 @@ Google Docs - edit documents using GitHub-flavored markdown. -pull downloads one markdown file per tab. Edit them, then push to sync back. - extrasuite docs pull <url> [output_dir] Download document as markdown extrasuite docs push <folder> Push local changes to Google Docs extrasuite docs create <title> Create a new document extrasuite docs share <url> <emails> Share with contacts -After pull, open index.md to orient yourself, then edit files in tabs/. - -Always re-pull after pushing before making more changes. +Pull creates a folder with index.md and a tabs/ directory. Open index.md first +— it lists every heading in every tab with its line number, so you can jump +directly to what you want to edit. Edit the files in tabs/ (one .md per tab); +each file has YAML frontmatter (id, title) at the top — don't remove it. To +add a tab, create a new .md file in tabs/ with frontmatter (set id to ""). +Standard GFM is supported: headings, bold/italic/strikethrough, inline code, +fenced code blocks, tables, bullet/numbered/checkbox lists, blockquotes, and +callouts ([!NOTE] [!WARNING] [!INFO] [!DANGER] [!TIP]). Cross-doc heading +links use [text](#Heading Name) or [text](#Tab/Heading Name). Existing images +appear as ![alt](uri) and are read-only. Always re-pull after push. diff --git a/client/src/extrasuite/client/help/doc/pull.md b/client/src/extrasuite/client/help/doc/pull.md index 8c0ad512..94da9e6e 100644 --- a/client/src/extrasuite/client/help/doc/pull.md +++ b/client/src/extrasuite/client/help/doc/pull.md @@ -1,61 +1,8 @@ Download a Google Doc as a folder of markdown files. -## Usage - extrasuite docs pull <url> [output_dir] -## Arguments - url Document URL or ID - output_dir Output directory (optional, defaults to <document_id>/ in CWD) - -## Output - - index.md Table of contents with line numbers (read-only, start here) - tabs/<Name>.md One markdown file per tab (edit these) - comments.xml Comments and replies (editable — see below) - .extrasuite/ Internal snapshot used by push — do not edit - -## Working with the files - -**index.md** lists every heading in every tab with its line number. Use it to -orient yourself and jump to the exact line you want to edit. - -**tabs/*.md** are the editable files. Each begins with YAML frontmatter (id, -title) — do not remove it. - -**New tabs**: create a new .md file in tabs/ with frontmatter. The filename -becomes the tab title (underscores become spaces). Push creates the tab. - - --- - id: "" - title: My New Tab - --- - -## Markdown features - -Standard GFM is supported: headings, bold, italic, strikethrough, `inline code`, -fenced code blocks, bullet/numbered/checkbox lists, pipe tables, and links. -Links to headings in the same doc use `[text](#Heading Name)` or -`[text](#Tab_Name/Heading Name)` for cross-tab. - -Blockquotes and callouts are supported: - > regular blockquote - > [!NOTE], [!WARNING], [!INFO], [!DANGER], [!TIP] - -Images are shown as `![alt](uri)`. The URI is a Google-hosted URL — you can -change the alt text but cannot insert new images via push. - -Horizontal rules, footnotes, section breaks, and TOC blocks are pulled as-is -and are read-only. - -## Comments - -comments.xml is pre-populated with existing comments. To add a reply or -resolve a comment, edit the file directly. Run `extrasuite docs help comments-reference` -for the format. - -## Example + output_dir Output directory (default: creates <document_id>/ in CWD) - extrasuite docs pull https://docs.google.com/document/d/abc123 - extrasuite docs pull https://docs.google.com/document/d/abc123 ./my-doc + --no-raw Skip saving raw API response to .extrasuite/document.json From f168b04f9bd57515249600e308eae240861450db Mon Sep 17 00:00:00 2001 From: Sripathi Krishnan <Sripathi.Krishnan@gmail.com> Date: Mon, 13 Apr 2026 13:39:07 +0530 Subject: [PATCH 4/4] client: simplify top-level discovery section to single line Remove the subcommand --help reference. Module --help is the right starting point; agents don't need to know about the subcommand level. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --- client/src/extrasuite/client/help/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/client/src/extrasuite/client/help/README.md b/client/src/extrasuite/client/help/README.md index 2fdb5abe..7b714e04 100644 --- a/client/src/extrasuite/client/help/README.md +++ b/client/src/extrasuite/client/help/README.md @@ -22,5 +22,4 @@ Make all changes locally and push once when done. Always re-pull before making f ## Discovery - extrasuite <module> --help Module overview: workflow, files, key rules - extrasuite <module> <cmd> --help Command flags and format reference (self-contained, no need to read module --help first) + extrasuite <module> --help Workflow, file format, and editing rules for that module