client: improve docs AX — markdown-first help text

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
     }
 )
 

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

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.

client/src/extrasuite/client/help/doc/pull.md

@@ -1,36 +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 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 (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
-filename (underscores become spaces). Push will create the tab in Google Docs.
-
-## 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