better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/productivity/productivity-docx.md

@@ -0,0 +1,213 @@
+---
+title: "Docx — Create, read, edit, template, and review Word .docx files"
+sidebar_label: "Docx"
+description: "Create, read, edit, template, and review Word .docx files"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Docx
+
+Create, read, edit, template, and review Word .docx files.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/productivity\docx` |
+| Version | `1.1.0` |
+| Author | Nous Research |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `word`, `docx`, `documents`, `office`, `templates`, `revisions`, `comments` |
+| Related skills | [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Docx Skill
+
+Create, read, edit, and template Microsoft Word `.docx` files with
+python-docx via small CLIs. It handles text, styles, lists, tables,
+images, headers/footers, `{{token}}` templating, tracked changes
+(list/accept/reject), comments (list/add/delete), TOC and page-number
+fields, and package health checks. It does not render documents itself
+(PDF needs LibreOffice — see Converting to PDF) or edit legacy `.doc`.
+
+## When to Use
+
+- The user asks to generate a Word document (report, letter, contract).
+- You need the text, outline, styles, or embedded images of a `.docx`.
+- You must change an existing `.docx`: replace text, edit table cells,
+  insert/delete paragraphs, apply styles, merge fragmented runs.
+- You have a `.docx` template with `{{placeholders}}` to fill from data.
+- The document has tracked changes to review, accept, or reject.
+- You need to read reviewers' comments, or add/delete comments.
+- A `.docx` won't open or behaves oddly and you need corruption triage.
+- The document needs a table of contents or "Page X of Y" footers.
+- Not for: `.doc` (legacy), `.odt`, or WYSIWYG layout work.
+
+## Prerequisites
+
+- Python 3.10+ with `python-docx` installed:
+  `pip install python-docx` (import name is `docx`; lxml comes with it).
+- Comments `add` uses the native API on python-docx >= 1.2 and an XML
+  fallback on older versions — both are automatic.
+- For image blocks: the image files must exist locally (PNG/JPEG).
+
+## How to Run
+
+All helpers live in `scripts/` next to this file. Run them with the
+`terminal` tool; each supports `--help` and prints JSON to stdout.
+
+```bash
+python scripts/docx_create.py spec.json out.docx
+python scripts/docx_read.py out.docx --text
+python scripts/docx_edit.py replace out.docx --find old --replace new
+python scripts/docx_template.py tpl.docx values.json filled.docx
+python scripts/docx_revisions.py list out.docx
+python scripts/docx_comments.py list out.docx
+python scripts/docx_validate.py out.docx
+```
+
+## Quick Reference
+
+| Task | Command |
+| --- | --- |
+| Create from JSON spec | `docx_create.py spec.json out.docx` |
+| Full text (body+tables+headers/footers) | `docx_read.py f.docx --text` |
+| Heading outline + table shapes | `docx_read.py f.docx --structure` |
+| Styles actually used | `docx_read.py f.docx --styles` |
+| Extract embedded images | `docx_read.py f.docx --images outdir/` |
+| Detect tracked changes/comments | `docx_read.py f.docx --revisions` |
+| Find/replace (formatting kept) | `docx_edit.py replace f.docx --find A --replace B -o out.docx` |
+| Set a table cell | `docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X` |
+| Insert paragraph before index N | `docx_edit.py insert f.docx --index N --text X --style Normal` |
+| Delete paragraph N | `docx_edit.py delete f.docx --index N` |
+| Apply style to paragraph N | `docx_edit.py style f.docx --index N --style "Heading 1"` |
+| Merge equal-format adjacent runs | `docx_edit.py normalize f.docx -o out.docx` |
+| Insert TOC field before para N | `docx_edit.py toc f.docx --index N -o out.docx` |
+| "Page X of Y" footer fields | `docx_edit.py page-numbers f.docx` |
+| Fill `{{tokens}}` | `docx_template.py tpl.docx values.json out.docx --strict` |
+| List revisions (id/author/date/text) | `docx_revisions.py list f.docx` |
+| Accept / reject all revisions | `docx_revisions.py accept-all f.docx -o out.docx` (or `reject-all`) |
+| Accept / reject one revision | `docx_revisions.py accept f.docx --id 3 -o out.docx` |
+| List comments (+anchored text) | `docx_comments.py list f.docx` |
+| Add comment anchored to text | `docx_comments.py add f.docx --target "phrase" --text "note" --author You` |
+| Delete comment by id | `docx_comments.py delete f.docx --id 0` |
+| Health-check the package | `docx_validate.py f.docx` (exit 1 on errors) |
+
+## Procedure
+
+1. **Create.** Write a JSON spec with `write_file`, then run
+   `scripts/docx_create.py`. The spec supports: `page` (size + margins in
+   mm), `header`/`footer` strings, `footer_page_numbers` (adds a
+   "Page X of Y" field footer), `styles` (custom paragraph styles with
+   font, size, bold/italic, hex `color`), and `blocks` — `heading`
+   (level 1-9), `paragraph` (either `text` or a `runs` list where each run
+   may set `bold`/`italic`/`underline`), `bullet_list`, `numbered_list`,
+   `table` (`header` row rendered bold, `rows`, optional built-in table
+   `style` such as `Table Grid`), `image` (`path`, optional `width_mm`),
+   `toc` (Table of Contents field), and `page_break`. The full spec
+   format is documented at the top of `scripts/docx_create.py`.
+2. **Read.** Use `scripts/docx_read.py` with exactly one mode flag.
+   `--text` returns body paragraphs, all table cell text, and
+   header/footer text as JSON. `--structure` returns the heading outline
+   plus paragraph/table/section counts. `--images DIR` copies every file
+   under `word/media/` out of the package.
+3. **Edit.** Use `scripts/docx_edit.py`. `replace` walks body, tables
+   (nested included), headers and footers, and preserves run formatting;
+   add `--body-only` to skip headers/footers. Pass `-o out.docx` to keep
+   the original; omit it to edit in place. Paragraph indices for
+   `insert`/`delete`/`style`/`toc` refer to `--structure`/`--text` body
+   order. Run `normalize` first on documents that came out of heavy Word
+   editing — it merges adjacent runs with identical formatting so later
+   find-replace matches reliably.
+4. **Review revisions.** `docx_revisions.py list` reports every `w:ins`
+   and `w:del` (id, author, date, affected text) anywhere in body,
+   tables, headers, or footers. `accept-all` / `reject-all` resolve them
+   in bulk; `accept`/`reject --id N` handles a single revision. Accept
+   keeps insertions and drops deleted text; reject does the reverse.
+5. **Comments.** `docx_comments.py list` returns each comment's id,
+   author, date, body text, and the document text it is anchored to.
+   `add --target "some phrase"` anchors a new comment to the first
+   occurrence of that phrase (runs are split as needed; formatting is
+   preserved). `delete --id N` removes the comment and its markers
+   without touching document text.
+6. **Template.** Put `{{name}}`-style tokens in the document. Run
+   `scripts/docx_template.py` with a JSON object of values. Use
+   `--strict` to fail when tokens remain unfilled; the JSON output lists
+   `filled` counts and `unfilled_tokens` either way.
+7. **Verify** (always): re-read the output with `--text` or
+   `--structure`, and run `docx_validate.py` on anything you produced
+   via revision/comment surgery.
+
+## Converting to PDF
+
+No script needed. When LibreOffice is installed, convert headlessly:
+
+```bash
+soffice --headless --convert-to pdf --outdir outdir/ file.docx
+```
+
+Check availability first (`command -v soffice || command -v
+libreoffice`). If neither exists, tell the user PDF conversion is
+unavailable in this environment rather than improvising — python-docx
+cannot render PDFs, and layout fidelity requires a real renderer.
+
+## Pitfalls
+
+- **Tokens split across runs.** Word often fragments text into several
+  runs. The replace helpers collapse matched runs (replacement inherits
+  the first run's formatting); running `docx_edit.py normalize` first
+  reduces fragmentation for all later edits.
+- **Revision coverage.** `docx_revisions.py` resolves run-level
+  insertions and deletions (the overwhelming majority). Paragraph-mark
+  and table-row revisions, format-change records, and moves are detected
+  by `--revisions` but not auto-resolved — see
+  `references/revisions-and-comments.md` and hand those to Word.
+- **Comment threading.** Replies and "resolved" status live in
+  `commentsExtended.xml`, which this skill ignores; comments it adds are
+  plain top-level comments.
+- **Field results are computed by Word.** `toc`, `page-numbers`, and the
+  `toc`/`footer_page_numbers` spec options write *field codes*.
+  Word/LibreOffice populates the actual entries and numbers when the
+  file is opened (Word may prompt to update fields); python-docx never
+  computes them, so placeholder text shows until then.
+- **Validation is a health check, not schema validation.**
+  `docx_validate.py` verifies the zip, required parts, relationship
+  targets, image magic bytes, and referenced styles. It is NOT XSD
+  validation — a file can pass and still contain XML Word dislikes.
+- **Style names must exist.** Applying a style that isn't defined in the
+  document raises `KeyError`. Built-ins like `Heading 1`, `List Bullet`,
+  `List Number`, `Table Grid` exist in the default template; custom
+  styles must be declared in the create spec first.
+- **Numbered lists restart.** `List Number` relies on Word's default
+  numbering; separate lists in one document may continue numbering
+  instead of restarting. Warn users needing precise multi-list numbering.
+- **Cell writes replace formatting.** `set-cell` uses `cell.text = ...`,
+  which resets runs in that cell to plain formatting.
+- **Encoding.** All JSON specs/values files are read as UTF-8 explicitly;
+  never rely on locale defaults when writing your own glue code.
+- **Don't unzip-and-sed the XML.** Edit through the scripts (or
+  python-docx); raw text substitution in `document.xml` corrupts files
+  easily. Use `patch`/`write_file` only for the JSON inputs, never on the
+  `.docx` itself.
+
+## Verification
+
+- After create/edit/template, run `docx_read.py out.docx --text` and
+  check the expected strings appear (and old strings are gone).
+- After accept/reject, `docx_revisions.py list` should return `[]` (or
+  only the ids you intentionally left); after comment surgery,
+  `docx_comments.py list` should reflect the change and `--text` output
+  must be unchanged.
+- `docx_validate.py out.docx` exits 0 with `"ok": true` on a healthy
+  package — run it after any revision/comment/field manipulation.
+- For templates run with `--strict`, or check `unfilled_tokens == []`.
+- Structure checks: `--structure` should show the expected heading
+  outline and table shapes; `--styles` confirms custom styles applied.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/productivity/productivity-google-workspace.md

@@ -0,0 +1,348 @@
+---
+title: "Google Workspace — Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python"
+sidebar_label: "Google Workspace"
+description: "Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Google Workspace
+
+Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/productivity\google-workspace` |
+| Version | `1.2.0` |
+| Author | Nous Research |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Google`, `Gmail`, `Calendar`, `Drive`, `Sheets`, `Docs`, `Contacts`, `Email`, `OAuth` |
+| Related skills | [`himalaya`](/docs/user-guide/skills/bundled/email/email-himalaya) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Google Workspace
+
+Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When `gws` is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.
+
+## References
+
+- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)
+- `references/daily-brief.md` — daily/morning brief procedure: schedule + conflicts + meeting prep + urgent mail from Gmail and Calendar. Load it when the user asks for a morning brief, meeting preparation, or "what's on my calendar and what email needs attention."
+
+## Scripts
+
+- `scripts/setup.py` — OAuth2 setup (run once to authorize)
+- `scripts/google_api.py` — compatibility wrapper CLI. It prefers `gws` for operations when available, while preserving Hermes' existing JSON output contract.
+
+## First-Time Setup
+
+The setup is fully non-interactive — you drive it step by step so it works
+on CLI, Telegram, Discord, or any platform.
+
+Define a shorthand first:
+
+```bash
+GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
+```
+
+### Step 0: Check if already set up
+
+```bash
+$GSETUP --check
+```
+
+If it prints `AUTHENTICATED`, skip to Usage — setup is already done.
+
+### Step 1: Triage — ask the user what they need
+
+Before starting OAuth setup, ask the user TWO questions:
+
+**Question 1: "What Google services do you need? Just email, or also
+Calendar/Drive/Sheets/Docs?"**
+
+- **Email only** → They don't need this skill at all. Use the `himalaya` skill
+  instead — it works with a Gmail App Password (Settings → Security → App
+  Passwords) and takes 2 minutes to set up. No Google Cloud project needed.
+  Load the himalaya skill and follow its setup instructions.
+
+- **Email + Calendar** → Continue with this skill, but use
+  `--services email,calendar` during auth so the consent screen only asks for
+  the scopes they actually need.
+
+- **Calendar/Drive/Sheets/Docs only** → Continue with this skill and use a
+  narrower `--services` set like `calendar,drive,sheets,docs`.
+
+- **Full Workspace access** → Continue with this skill and use the default
+  `all` service set.
+
+**Question 2: "Does your Google account use Advanced Protection (hardware
+security keys required to sign in)? If you're not sure, you probably don't
+— it's something you would have explicitly enrolled in."**
+
+- **No / Not sure** → Normal setup. Continue below.
+- **Yes** → Their Workspace admin must add the OAuth client ID to the org's
+  allowed apps list before Step 4 will work. Let them know upfront.
+
+### Step 2: Create OAuth credentials (one-time, ~5 minutes)
+
+Tell the user:
+
+> You need a Google Cloud OAuth client. This is a one-time setup:
+>
+> 1. Create or select a project:
+>    https://console.cloud.google.com/projectselector2/home/dashboard
+> 2. Enable the required APIs from the API Library:
+>    https://console.cloud.google.com/apis/library
+>    Enable: Gmail API, Google Calendar API, Google Drive API,
+>    Google Sheets API, Google Docs API, People API
+> 3. Create the OAuth client here:
+>    https://console.cloud.google.com/apis/credentials
+>    Credentials → Create Credentials → OAuth 2.0 Client ID
+> 4. Application type: "Desktop app" → Create
+> 5. If the app is still in Testing, add the user's Google account as a test user here:
+>    https://console.cloud.google.com/auth/audience
+>    Audience → Test users → Add users
+> 6. Download the JSON file and tell me the file path
+>
+> Important Hermes CLI note: if the file path starts with `/`, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:
+> `The JSON file path is: ~/Downloads/client_secret_....json`
+
+Once they provide the path:
+
+```bash
+$GSETUP --client-secret /path/to/client_secret.json
+```
+
+If they paste the raw client ID / client secret values instead of a file path,
+write a valid Desktop OAuth JSON file for them yourself, save it somewhere
+explicit (for example `~/Downloads/hermes-google-client-secret.json`), then run
+`--client-secret` against that file.
+
+### Step 3: Get authorization URL
+
+Use the service set chosen in Step 1. Examples:
+
+```bash
+$GSETUP --auth-url --services email,calendar --format json
+$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
+$GSETUP --auth-url --services all --format json
+```
+
+This returns JSON with an `auth_url` field and also saves the exact URL to
+`~/.hermes/google_oauth_last_url.txt`.
+
+Agent rules for this step:
+- Extract the `auth_url` field and send that exact URL to the user as a single line.
+- Tell the user that the browser will likely fail on `http://localhost:1` after approval, and that this is expected.
+- Tell them to copy the ENTIRE redirected URL from the browser address bar.
+- If the user gets `Error 403: access_denied`, send them directly to `https://console.cloud.google.com/auth/audience` to add themselves as a test user.
+
+### Step 4: Exchange the code
+
+The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...`
+or just the code string. Either works. The `--auth-url` step stores a temporary
+pending OAuth session locally so `--auth-code` can complete the PKCE exchange
+later, even on headless systems:
+
+```bash
+$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
+```
+
+If `--auth-code` fails because the code expired, was already used, or came from
+an older browser tab, it now returns a fresh `fresh_auth_url`. In that case,
+immediately send the new URL to the user and have them retry with the newest
+browser redirect only.
+
+### Step 5: Verify
+
+```bash
+$GSETUP --check
+```
+
+Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.
+
+### Notes
+
+- Token is stored at `~/.hermes/google_token.json` and auto-refreshes.
+- Pending OAuth session state/verifier are stored temporarily at `~/.hermes/google_oauth_pending.json` until exchange completes.
+- If `gws` is installed, `google_api.py` points it at the same `~/.hermes/google_token.json` credentials file. Users do not need to run a separate `gws auth login` flow.
+- To revoke: `$GSETUP --revoke`
+
+## Usage
+
+All commands go through the API script. Set `GAPI` as a shorthand:
+
+```bash
+GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
+```
+
+### Gmail
+
+```bash
+# Search (returns JSON array with id, from, subject, date, snippet)
+$GAPI gmail search "is:unread" --max 10
+$GAPI gmail search "from:boss@company.com newer_than:1d"
+$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
+
+# Read full message (returns JSON with body text)
+$GAPI gmail get MESSAGE_ID
+
+# Send
+$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
+$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
+$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"
+
+# Reply (automatically threads and sets In-Reply-To)
+$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
+$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"
+
+# Labels
+$GAPI gmail labels
+$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
+$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
+```
+
+### Calendar
+
+```bash
+# List events (defaults to next 7 days)
+$GAPI calendar list
+$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
+
+# Create event (ISO 8601 with timezone required)
+$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
+$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
+$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"
+
+# Delete event
+$GAPI calendar delete EVENT_ID
+```
+
+### Drive
+
+```bash
+# Search existing files
+$GAPI drive search "quarterly report" --max 10
+$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
+
+# Get metadata for a single file
+$GAPI drive get FILE_ID
+
+# Upload a local file (auto-detects MIME type)
+$GAPI drive upload /path/to/report.pdf
+$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID
+
+# Download (binary files download as-is; Google-native files export to a
+# sensible default — Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png)
+$GAPI drive download FILE_ID
+$GAPI drive download DOC_ID --output ~/doc.pdf
+$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt
+
+# Create a folder
+$GAPI drive create-folder "Reports"
+$GAPI drive create-folder "Q4" --parent FOLDER_ID
+
+# Share
+$GAPI drive share FILE_ID --email alice@example.com --role reader
+$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
+$GAPI drive share FILE_ID --type anyone --role reader        # anyone with link
+$GAPI drive share FILE_ID --type domain --domain example.com --role reader
+
+# Delete — defaults to trash (reversible). Use --permanent to skip the trash.
+$GAPI drive delete FILE_ID
+$GAPI drive delete FILE_ID --permanent
+```
+
+### Contacts
+
+```bash
+$GAPI contacts list --max 20
+```
+
+### Sheets
+
+```bash
+# Create a new spreadsheet
+$GAPI sheets create --title "Q4 Budget"
+$GAPI sheets create --title "Inventory" --sheet-name "Stock"
+
+# Read
+$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
+
+# Write
+$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
+
+# Append rows
+$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
+```
+
+### Docs
+
+```bash
+# Read
+$GAPI docs get DOC_ID
+
+# Create a new Doc (optionally seeded with body text)
+$GAPI docs create --title "Meeting Notes"
+$GAPI docs create --title "Draft" --body "First paragraph..."
+
+# Append text to the end of an existing Doc
+$GAPI docs append DOC_ID --text "Additional content to append"
+```
+
+## Output Format
+
+All commands return JSON. Parse with `jq` or read directly. Key fields:
+
+- **Gmail search**: `[{id, threadId, from, to, subject, date, snippet, labels}]`
+- **Gmail get**: `{id, threadId, from, to, subject, date, labels, body}`
+- **Gmail send/reply**: `{status: "sent", id, threadId}`
+- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
+- **Calendar create**: `{status: "created", id, summary, htmlLink}`
+- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
+- **Drive get**: `{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}`
+- **Drive upload**: `{status: "uploaded", id, name, mimeType, webViewLink}`
+- **Drive download**: `{status: "downloaded", id, name, path, mimeType}`
+- **Drive create-folder**: `{status: "created", id, name, webViewLink}`
+- **Drive share**: `{status: "shared", permissionId, fileId, role, type}`
+- **Drive delete**: `{status: "trashed" | "deleted", fileId, permanent}`
+- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
+- **Sheets get**: `[[cell, cell, ...], ...]`
+- **Sheets create**: `{status: "created", spreadsheetId, title, spreadsheetUrl}`
+- **Docs create**: `{status: "created", documentId, title, url}`
+- **Docs append**: `{status: "appended", documentId, inserted_at, characters}`
+
+## Rules
+
+1. **Never send email, create/delete calendar events, delete Drive files, share files, or modify Docs/Sheets without confirming with the user first.** Show what will be done (recipients, file IDs, content, share role) and ask for approval. For `drive delete`, prefer the default trash (reversible) over `--permanent`.
+2. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.
+3. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.
+4. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).
+5. **Respect rate limits** — avoid rapid-fire sequential API calls. Batch reads when possible.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `NOT_AUTHENTICATED` | Run setup Steps 2-5 above |
+| `REFRESH_FAILED` | Token revoked or expired — redo Steps 3-5 |
+| `HttpError 403: Insufficient Permission` | Missing API scope — `$GSETUP --revoke` then redo Steps 3-5 |
+| `AUTHENTICATED (partial)` or "Token missing scopes" | New write capabilities (Drive write/delete, Docs create/edit) require re-authorization. `$GSETUP --revoke` then redo Steps 3-5 to grant the upgraded scopes. |
+| `HttpError 403: Access Not Configured` | API not enabled — user needs to enable it in Google Cloud Console |
+| `ModuleNotFoundError` | Run `$GSETUP --install-deps` |
+| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
+
+## Revoking Access
+
+```bash
+$GSETUP --revoke
+```