mercury-agent 0.4.5

package/examples/extensions/gws/skill/references/docs.md

@@ -0,0 +1,65 @@
+# Docs Reference
+
+Use `gws docs` for reading and writing Google Docs.
+
+## Read a document
+
+First find the document ID from Drive:
+
+```bash
+# Find document by name
+gws drive files list --params '{"q":"name contains '\''Meeting Notes'\'' and mimeType = '\''application/vnd.google-apps.document'\''","pageSize":5}'
+```
+
+Then export its content as plain text:
+
+```bash
+gws drive files export --params '{"fileId":"<DOC_ID>","mimeType":"text/plain"}' --output /tmp/doc.txt
+cat /tmp/doc.txt
+```
+
+## Summarize a document
+
+Read the document with the export method above, then summarize the content in plain language. Never paste the raw text export as-is — always translate into a concise summary.
+
+## Append text to a document
+
+```bash
+gws docs +write --document <DOC_ID> --text 'New paragraph to append.'
+```
+
+Text is inserted at the end of the document body. For multiline content, use `$'...'` shell quoting:
+
+```bash
+gws docs +write --document <DOC_ID> --text $'Line one.\nLine two.'
+```
+
+## Read document metadata
+
+```bash
+gws docs documents get --params '{"documentId":"<DOC_ID>"}'
+```
+
+Useful fields: `title`, `body.content` (structured content). For plain reading, prefer the Drive export approach above.
+
+## Raw API fallback
+
+```bash
+gws docs --help   # list all subcommands
+gws docs documents --help
+```
+
+For rich formatting (headings, bold, tables), use the raw `documents.batchUpdate` API:
+
+```bash
+gws docs documents batchUpdate \
+  --params '{"documentId":"<DOC_ID>"}' \
+  --json '{"requests":[{"insertText":{"location":{"index":1},"text":"Hello\n"}}]}'
+```
+
+## Output format rules
+
+- Document found: say "I found your doc — [title]"
+- Summary: present as a plain paragraph or bullet list of key points
+- Append confirmation: "Added your text to '[document title]'"
+- Never show document IDs, revision IDs, or raw JSON content structures

package/examples/extensions/gws/skill/references/drive.md

@@ -0,0 +1,79 @@
+# Drive Reference
+
+Use `gws drive` for all Google Drive operations.
+
+## List files in root (My Drive)
+
+```bash
+gws drive files list --params '{"pageSize":20}'
+```
+
+Response fields to use: `name`, `mimeType`, `modifiedTime`. Never show `id` to the user — keep it for follow-up commands.
+
+## List files in a specific folder
+
+First get the folder ID from a `files list` call (store internally):
+
+```bash
+# Find folder by name
+gws drive files list --params '{"q":"name = '\''Reports'\'' and mimeType = '\''application/vnd.google-apps.folder'\''","pageSize":5}'
+
+# List files inside the folder
+gws drive files list --params '{"q":"'\''<FOLDER_ID>'\'' in parents","pageSize":20}'
+```
+
+## Search by name
+
+```bash
+gws drive files list --params '{"q":"name contains '\''budget'\''","pageSize":10}'
+```
+
+## Upload a file
+
+```bash
+# Upload to root
+gws drive +upload ./report.pdf
+
+# Upload to a specific folder
+gws drive +upload ./report.pdf --parent <FOLDER_ID>
+
+# Upload with a custom name
+gws drive +upload ./data.csv --name 'Sales Data Q1.csv'
+```
+
+## Create a folder
+
+```bash
+gws drive files create --json '{"name":"New Folder","mimeType":"application/vnd.google-apps.folder"}'
+
+# Inside an existing folder
+gws drive files create --json '{"name":"Sub Folder","mimeType":"application/vnd.google-apps.folder","parents":["<PARENT_FOLDER_ID>"]}'
+```
+
+## Move a file to a folder
+
+```bash
+gws drive files update --params '{"fileId":"<FILE_ID>","addParents":"<FOLDER_ID>","removeParents":"root"}'
+```
+
+## Download a file
+
+```bash
+gws drive files download --params '{"fileId":"<FILE_ID>"}' --output ./downloaded-file.pdf
+
+# Export a Google Doc as plain text
+gws drive files export --params '{"fileId":"<DOC_ID>","mimeType":"text/plain"}' --output ./doc.txt
+```
+
+## Raw API fallback
+
+```bash
+gws drive files --help   # list all files subcommands
+```
+
+## Output format rules
+
+- List files as: "1. Budget 2026 (Google Sheets) — modified 3 days ago"
+- Translate MIME types: `application/vnd.google-apps.document` → "Google Doc", `application/vnd.google-apps.spreadsheet` → "spreadsheet", `application/vnd.google-apps.folder` → "folder", `application/pdf` → "PDF"
+- Never show `fileId`, `parents`, or any other ID field
+- Upload confirmation: "Uploaded report.pdf to your Drive" (or "to the Reports folder" if parent specified)

package/examples/extensions/gws/skill/references/gmail.md

@@ -0,0 +1,85 @@
+# Gmail Reference
+
+Use `gws gmail` for all email operations. All helpers are read-only except `+send`, `+reply`, `+reply-all`, and `+forward`.
+
+## Triage inbox
+
+```bash
+# Show unread messages (default: 20)
+gws gmail +triage
+
+# Limit count or filter by search query
+gws gmail +triage --max 10
+gws gmail +triage --query 'from:boss@example.com'
+gws gmail +triage --query 'is:unread subject:invoice'
+```
+
+Output fields: sender, subject, date. Never show `messageId`, `threadId`, or `labelIds`.
+
+## Read a message
+
+First get the message ID from `+triage` output (use internally only — never show it to the user).
+
+```bash
+gws gmail +read --id <MESSAGE_ID>
+gws gmail +read --id <MESSAGE_ID> --headers    # includes From, To, Subject, Date
+```
+
+Present: sender name, subject, date, and a plain-text summary of the body.
+
+## Send a new email
+
+```bash
+gws gmail +send --to alice@example.com --subject 'Hello' --body 'Hi Alice!'
+
+# With CC / BCC
+gws gmail +send --to alice@example.com --subject 'Report' --body 'See attached' \
+  --cc bob@example.com --bcc charlie@example.com
+
+# With attachment
+gws gmail +send --to alice@example.com --subject 'Report' --body 'Attached.' -a report.pdf
+
+# Save as draft first, then confirm with user before sending
+gws gmail +send --to alice@example.com --subject 'Hello' --body 'Hi!' --draft
+```
+
+Always confirm recipient and subject with the user before sending.
+
+## Reply to a message
+
+```bash
+gws gmail +reply --message-id <MESSAGE_ID> --body 'Thanks, got it!'
+
+# Reply-all
+gws gmail +reply-all --message-id <MESSAGE_ID> --body 'Noted — will follow up.'
+```
+
+Handles threading (In-Reply-To, References) automatically.
+
+## Forward a message
+
+```bash
+gws gmail +forward --message-id <MESSAGE_ID> --to dave@example.com
+gws gmail +forward --message-id <MESSAGE_ID> --to dave@example.com --body 'FYI see below'
+```
+
+## Raw API fallback
+
+```bash
+# List messages with custom query
+gws gmail users messages list --params '{"userId":"me","q":"is:unread","maxResults":10}'
+
+# Get message metadata
+gws gmail users messages get --params '{"userId":"me","id":"<MESSAGE_ID>","format":"metadata"}'
+
+# Modify labels (e.g. archive = remove INBOX label)
+gws gmail users messages modify --params '{"userId":"me","id":"<MESSAGE_ID>"}' \
+  --json '{"removeLabelIds":["INBOX"]}'
+```
+
+## Output format rules
+
+- Show sender name and subject; never show `messageId`, `threadId`, or `labelIds`
+- Present a triage summary as a numbered list: "1. From Alice — Re: Invoice (2 hours ago)"
+- For send/reply confirmations: "Sent to Alice — subject: Hello"
+- Errors: say "I couldn't send the email" — never show HTTP status codes or API error objects

package/examples/extensions/gws/skill/references/sheets.md

@@ -0,0 +1,60 @@
+# Sheets Reference
+
+Use `gws sheets` for reading and writing Google Sheets.
+
+## Read values from a spreadsheet
+
+First find the spreadsheet ID from Drive (store internally — never show to user):
+
+```bash
+# Find spreadsheet by name
+gws drive files list --params '{"q":"name contains '\''Budget'\'' and mimeType = '\''application/vnd.google-apps.spreadsheet'\''","pageSize":5}'
+```
+
+Then read a range:
+
+```bash
+# Read a named range or A1 notation
+gws sheets +read --spreadsheet <SPREADSHEET_ID> --range 'Sheet1!A1:D10'
+
+# Read an entire sheet (by tab name)
+gws sheets +read --spreadsheet <SPREADSHEET_ID> --range Sheet1
+```
+
+Present the data as a plain summary or a simple list — not as a raw JSON array.
+
+## Append a row
+
+```bash
+# Simple comma-separated values (single row)
+gws sheets +append --spreadsheet <SPREADSHEET_ID> --values 'Alice,100,true'
+
+# Multiple rows (JSON array of arrays)
+gws sheets +append --spreadsheet <SPREADSHEET_ID> \
+  --json-values '[["Alice","100","true"],["Bob","200","false"]]'
+```
+
+Values are appended after the last row that contains data.
+
+## Read all data and summarize
+
+```bash
+gws sheets +read --spreadsheet <SPREADSHEET_ID> --range Sheet1 --format table
+```
+
+Parse the table output to provide a plain-language summary (e.g. "The sheet has 42 rows. The highest value in column B is 250.").
+
+## Raw API fallback
+
+```bash
+gws sheets spreadsheets get --params '{"spreadsheetId":"<SPREADSHEET_ID>"}'   # metadata + sheet names
+gws sheets spreadsheets values get --params '{"spreadsheetId":"<SPREADSHEET_ID>","range":"Sheet1!A1:Z100"}'
+gws sheets --help   # list all subcommands
+```
+
+## Output format rules
+
+- Read results: present as a short prose summary or a simple list — never paste raw JSON arrays
+- Append confirmation: "Added a row to '[spreadsheet name]'"
+- Never show spreadsheet IDs, sheet GIDs, or raw cell object structures
+- If the range is empty, say "That range appears to be empty"