mercury-agent 0.5.0 → 0.5.2

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

@@ -1,65 +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
+# 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

@@ -1,79 +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)
+# 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

@@ -1,85 +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
+# 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

@@ -1,60 +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"
+# 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"