docs: document helper commands and the + prefix convention (#427)

* docs: document helper commands and the + prefix convention

Add a "Helper Commands" section to the Advanced Usage chapter of the
README explaining:

- What the `+` prefix means and why it exists (visually distinct from
  Discovery-generated method names, no collision risk)
- How to discover helpers via `gws <service> --help`
- A full reference table of all 23 helper commands across 11 services
- Usage examples for the most common helpers (gmail, sheets, calendar,
  drive, workflow)

Fixes discoverability gap: users had no way to learn about helper
commands without reading the source code.

* fix(docs): correct +append and +upload examples per Gemini review

- gws sheets +append: flag is --spreadsheet (not --spreadsheet-id) and
  +append has no --range argument
- gws drive +upload: file path is a positional argument, not --file flag

* docs: clarify script +push is destructive (replaces, not adds)

The +push helper replaces all files in an Apps Script project.
Update description to reflect this so users understand the action
is destructive before running it.

Addresses code-review feedback.

* chore(changeset): correct helper command count to 24 across 10 services

Addresses code-review feedback noting the count was off.

.changeset/document-helper-commands.md

@@ -0,0 +1,9 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Document helper commands (`+` prefix) in README
+
+Adds a "Helper Commands" section to the Advanced Usage chapter explaining
+the `+` prefix convention, listing all 24 helper commands across 10 services
+with descriptions and usage examples.

README.md

@@ -286,6 +286,69 @@ gws sheets spreadsheets values append \
   --json '{"values": [["Name", "Score"], ["Alice", 95]]}'
 ```
 
+### Helper Commands
+
+Some services ship hand-crafted helper commands alongside the auto-generated Discovery surface. Helper commands are prefixed with `+` so they are visually distinct and never collide with Discovery-generated method names.
+
+Run `gws <service> --help` to see both Discovery methods and helper commands together.
+
+```bash
+gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
+gws calendar --help   # shows +insert, +agenda …
+gws drive --help      # shows +upload …
+```
+
+**Full helper reference:**
+
+| Service | Command | Description |
+|---------|---------|-------------|
+| `gmail` | `+send` | Send an email |
+| `gmail` | `+reply` | Reply to a message (handles threading automatically) |
+| `gmail` | `+reply-all` | Reply-all to a message |
+| `gmail` | `+forward` | Forward a message to new recipients |
+| `gmail` | `+triage` | Show unread inbox summary (sender, subject, date) |
+| `gmail` | `+watch` | Watch for new emails and stream them as NDJSON |
+| `sheets` | `+append` | Append a row to a spreadsheet |
+| `sheets` | `+read` | Read values from a spreadsheet |
+| `docs` | `+write` | Append text to a document |
+| `chat` | `+send` | Send a message to a space |
+| `drive` | `+upload` | Upload a file with automatic metadata |
+| `calendar` | `+insert` | Create a new event |
+| `calendar` | `+agenda` | Show upcoming events across all calendars |
+| `script` | `+push` | Replace all files in an Apps Script project with local files |
+| `workflow` | `+standup-report` | Today's meetings + open tasks as a standup summary |
+| `workflow` | `+meeting-prep` | Prepare for your next meeting: agenda, attendees, and linked docs |
+| `workflow` | `+email-to-task` | Convert a Gmail message into a Google Tasks entry |
+| `workflow` | `+weekly-digest` | Weekly summary: this week's meetings + unread email count |
+| `workflow` | `+file-announce` | Announce a Drive file in a Chat space |
+| `events` | `+subscribe` | Subscribe to Workspace events and stream them as NDJSON |
+| `events` | `+renew` | Renew/reactivate Workspace Events subscriptions |
+| `modelarmor` | `+sanitize-prompt` | Sanitize a user prompt through a Model Armor template |
+| `modelarmor` | `+sanitize-response` | Sanitize a model response through a Model Armor template |
+| `modelarmor` | `+create-template` | Create a new Model Armor template |
+
+**Examples:**
+
+```bash
+# Send an email
+gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
+
+# Reply to a message
+gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"
+
+# Append a row to a spreadsheet
+gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"
+
+# Show today's calendar agenda
+gws calendar +agenda
+
+# Upload a file to Drive
+gws drive +upload ./report.pdf --name "Q1 Report"
+
+# Morning standup summary
+gws workflow +standup-report
+```
+
 ### Model Armor (Response Sanitization)
 
 Integrate [Google Cloud Model Armor](https://cloud.google.com/security/products/model-armor) to scan API responses for prompt injection before they reach your agent.