@qvac/skills 0.0.0 → 0.1.1

package/skills/excel/references/edit.md

@@ -0,0 +1,353 @@
+# Editing an Attached Workbook (openpyxl)
+
+Edit a workbook that is already in this chat by running Python through the
+`exec` tool: change cells, add or insert rows, add columns or sheets, delete
+rows, columns, or sheets. Stage the workbook as an input, modify it, and save
+under a **new** output name such as `revised.xlsx` — never overwrite the staged
+input.
+
+Macro-enabled files (`.xlsm`) can be staged as inputs and read, but this
+runtime cannot deliver `.xlsm` back — macros never survive. Save the edit as
+`.xlsx` and tell the user the macros were not preserved.
+
+## Staging the Workbook
+
+**A workbook you built earlier in this chat is edited exactly like any other
+attachment — through its id.** The `exec` result that produced it carried
+`attachments: [{ attachmentId, fileName, byteLength }]`; scroll back, copy that
+`attachmentId` character for character, and stage it. The working directory is
+wiped between calls, so a file you saved last turn is not on disk — without a
+staged input `load_workbook("report.xlsx")` raises
+`FileNotFoundError: [Errno 44] No such file or directory`.
+
+```json
+{
+  "language": "python",
+  "packages": ["openpyxl==3.1.5"],
+  "inputs": [{ "attachmentId": "<the id from the earlier exec result>", "path": "existing.xlsx" }],
+  "outputs": ["revised.xlsx"],
+  "command": "..."
+}
+```
+
+**A workbook the user uploaded is staged the same way — by its id.** The
+`[Attached file …]` line on their message names it:
+
+```
+[Attached file "budget.xlsx" (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) — attachmentId: 4f9c2ab1]
+```
+
+Copy that id verbatim into `attachmentId`, exactly as for a workbook a tool
+produced. This holds for **`.csv` and `.xlsm` uploads too**, not just `.xlsx`: an
+id-less entry resolves to an uploaded *image*, so any `inputs` entry whose `path`
+names a data or document file is rejected outright. Only an uploaded **image** is
+staged with `path` alone and no `attachmentId` key.
+
+Staged files land in the working directory under the bare `path` names —
+reference `load_workbook("existing.xlsx")` by that name only.
+`attachment … not found in this chat` means you invented an id or the file is not
+attached. Re-copy the exact id from the `exec` result or the `[Attached file …]`
+line that names the workbook; if no id appears anywhere in the chat, ask the
+user to attach the file again.
+
+`wb.save("revised.xlsx")` must match the declared output name. Keep the
+`command` source multi-line with real newlines — never collapse it with `;`.
+
+## Adding an Image to an Existing Workbook
+
+Stage two files: the workbook by its `attachmentId`, and the picture. Add `"pillow"`
+to `packages` — **deliberately unpinned**, since the runtime owns its version and a
+pin sends openpyxl to PyPI with it.
+
+```json
+{
+  "language": "python",
+  "packages": ["openpyxl==3.1.5", "pillow"],
+  "inputs": [
+    { "attachmentId": "<id of the workbook>", "path": "existing.xlsx" },
+    { "attachmentId": "<id from the generate_image result>", "path": "photo.png" }
+  ],
+  "outputs": ["revised.xlsx"],
+  "command": "..."
+}
+```
+
+`path` is a name you choose; it has nothing to do with the attachment id, and a
+`fileName` seen in a tool result is not a file on disk. A `generate_image` result
+anywhere in the conversation is the image the request points at — stage that id
+rather than asking the user to attach it again.
+
+```python
+from openpyxl.drawing.image import Image as XLImage
+
+img = XLImage("photo.png")           # the path from inputs, nothing else
+img.width, img.height = 320, 320     # pixels
+ws.add_image(img, "A1")              # a worksheet method; A1 is the top-left corner
+```
+
+One `add_image` per workbook — inside a loop over sheets it embeds a copy per sheet.
+Never wrap the import or the call in a `try`/`except` that saves anyway.
+
+## The Golden Rule of Edits
+
+**The staged sheet already has its header and all its data.** Editing never
+re-creates them: no `HEADERS`, no `ROWS`, no copy of the create template. Append
+only what is genuinely new, and change only the cells you were asked to change.
+Re-appending the header and the rows writes the whole table a second time and the
+user opens a file where every row appears twice — the create template belongs to
+the create path (`references/create.md`) and nowhere else.
+
+Adding one row is the whole program:
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("existing.xlsx")
+ws = wb.active                       # wb["Sheet Name"] to pick another
+
+before = ws.max_row                  # the sheet is already this long
+ws.append([2026, 82500, 135000, 107500])
+
+wb.save("revised.xlsx")              # NEW name, matching the declared output
+print(f"{before} rows in, {ws.max_row} rows out")
+```
+
+That print is the check: one added row means the count goes up by exactly one. If
+it roughly doubles, the run re-appended the existing data — fix it and rerun
+rather than delivering a workbook with the table in it twice.
+
+## Putting the Row Where It Belongs
+
+Appending is right when the table has no order, and wrong when it has one: a sheet
+running 2016…2026 with 2015 stuck on the end reads as broken. When the new row
+belongs inside an existing order, insert it at that position instead.
+
+You already know the position — 2015 sorts above 2016, and the data starts at row 2
+— so write the index as a number. Do not scan, sort, or compare anything to work it
+out:
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("existing.xlsx")
+ws = wb.active
+
+ROW = [2015, 278, 930, 45.5]
+AT = 2                               # 2015 goes above 2016 — row 1 is the header
+
+assert not any(m.max_row >= AT for m in ws.merged_cells.ranges) and not any(
+    isinstance(c.value, str) and c.value.startswith("=") for r in ws.iter_rows() for c in r
+), "a merged range at or below AT, or a formula — append instead, their ranges do not move"
+
+before = ws.max_row
+ws.insert_rows(AT)
+for column, value in enumerate(ROW, start=1):
+    cell = ws.cell(row=AT, column=column, value=value)
+    cell.number_format = ws.cell(row=AT + 1, column=column).number_format
+
+wb.save("revised.xlsx")
+print(f"{before} rows in, {ws.max_row} rows out")
+```
+
+`AT` is never `1` — that would push the header down into the data.
+
+The two lines that look optional are the ones that matter. An inserted cell starts
+with no number format, so without the copy the new row shows a bare `278` in a
+column of `278.00`s; taking the format from `AT + 1` uses the row that used to sit
+there. And `insert_rows` moves cells but neither formula ranges nor merged ranges,
+so a `=SUM(B2:B11)` total would go on summing the old span and quietly leave the
+new row out, while a `Total` merged across `A8:B8` would stay pinned to row 8 as
+its row slid to 9 — the assert stops both before anything is saved.
+
+The two halves are scoped differently on purpose. A merged range is disturbed only
+if it sits at or below `AT`, which is why the check is `m.max_row >= AT` rather than
+"any merged cell": a title merged across `A1:C1` is untouched by an insert further
+down, and failing on it would push you to append out of order for no reason. A
+formula gives no such signal — one in `D1` can reference `B2:B11` — so any formula
+at all is enough to stop the insert.
+
+When the assert fires, do not delete it. Append the row at the end with the
+previous template and tell the user the table kept its file order so their totals
+stay correct.
+
+## Other Edits — Touch Only What Changes
+
+```python
+from openpyxl import load_workbook
+from openpyxl.styles import Font
+
+wb = load_workbook("existing.xlsx")
+ws = wb["Q1 Sales"]                  # or wb.active; wb.sheetnames lists them
+
+ws.cell(row=1, column=5, value="Margin %").font = Font(bold=True)
+for row, margin in [(2, 0.31), (3, 0.42), (4, 0.18)]:
+    cell = ws.cell(row=row, column=5, value=margin)
+    cell.number_format = '0.0%'
+
+ws["B2"] = 150                       # update a cell in place
+
+notes = wb.create_sheet("Notes")
+notes["A1"] = "Updated unit counts for North"
+
+wb.save("revised.xlsx")              # NEW name, matching the declared output
+print(f"{len(wb.sheetnames)} sheets: {wb.sheetnames}")
+```
+
+`wb["Sheet Name"]` raises `KeyError` when the name does not exist — when unsure,
+print `wb.sheetnames` in the same run that edits, pick from it, and never guess.
+
+## Deleting Rows, Columns and Sheets
+
+openpyxl deletes for real, so none of this needs XML work. `ws.delete_rows(index)`
+and `ws.delete_cols(index)` take a **1-based** index and an optional count, so
+`ws.delete_rows(5, 3)` drops rows 5, 6 and 7 together; a sheet goes with
+`del wb["Notes"]`. Row 1 is the header — `delete_rows(1)` throws it away, and data
+rows start at 2, exactly as for an insert.
+
+**Delete from the bottom up.** Each delete shifts everything below it, so a loop
+over ascending indices removes the wrong rows after the first: dropping rows 3 and
+5 top-down deletes row 3, then deletes what used to be row 6. Collect the row
+numbers first and walk them in reverse — the same rule applies right-to-left for
+`delete_cols`:
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("existing.xlsx")
+ws = wb.active
+
+DROP = (2021, 2023)                  # the column-A values whose rows go
+
+before = ws.max_row
+targets = [r for r in range(2, ws.max_row + 1) if ws.cell(row=r, column=1).value in DROP]
+assert targets, f"no row matched {DROP} — check the values are numbers, not strings"
+
+assert not any(m.max_row >= min(targets) for m in ws.merged_cells.ranges) and not any(
+    isinstance(c.value, str) and c.value.startswith("=") for r in ws.iter_rows() for c in r
+), "a merged range at or below the first deleted row, or a formula — their ranges do not move"
+
+for row in reversed(targets):        # bottom-up; ascending order deletes the wrong rows
+    ws.delete_rows(row)
+
+wb.save("revised.xlsx")              # NEW name, matching the declared output
+print(f"{before} rows in, {ws.max_row} rows out")
+```
+
+The `assert targets` line is what stops a no-op being delivered, and it belongs
+before the loop rather than after it. Without it, values that match nothing leave
+the sheet untouched and the workbook still saves at `exitCode 0` with an
+attachment indistinguishable from a real delete. With it the run raises, nothing
+is written, and the result carries `missingOutputs` instead. The usual cause is a
+type mismatch — the string `"2021"` is not the number `2021` — or a wrong column
+index. **An assert that fires is a failed turn to diagnose, not a workbook to
+deliver**: fix the match and rerun, and never delete the assert to get a file out.
+The printed `rows in / rows out` line is then the reply line, not the check, and it
+still costs no extra call — both live in the run that does the deleting.
+
+The second assert is the `insert_rows` hazard in reverse, and it covers the same two
+things with the same scoping. `delete_rows` moves cells but leaves formula text
+alone, so a `=SUM(B2:B11)` total goes on summing eleven rows of a table that now
+holds nine, pulling in blanks or the wrong cells. It leaves merged ranges alone too:
+a `Total` merged at `A8:B8` keeps covering row 8 after a row above it is deleted, and
+a title merged across `A1:C1` still claims three columns after a `delete_cols`. Both
+are silent — no error, and the damage only shows when the user opens the file.
+
+Merges are again checked from the first deleted row down (`m.max_row >= min(targets)`),
+so a banner above every deletion does not block the edit, while any formula anywhere
+does. When it fires, do not delete it: say which rows you would have removed and ask
+whether to drop the merges and formulas too, or tell the user the deletion has to
+happen in Excel, where the ranges follow. Note the column case is not covered by that
+row check — if you are calling `delete_cols` on a sheet with horizontal merges, treat
+any merged range as a stop.
+
+## Reading Cell Values During an Edit
+
+`load_workbook` has two modes, and neither gives both formulas and values:
+
+- `load_workbook("f.xlsx")` — formula cells hold the formula **string**
+  (`"=SUM(D2:D4)"`).
+- `load_workbook("f.xlsx", data_only=True)` — formula cells hold the value the
+  last spreadsheet app **cached** when it saved. A file that openpyxl itself wrote
+  has no cache, so these cells read `None`.
+
+Plain data cells read the same either way. When a formula cell reads `None` under
+`data_only=True`, the file was never recalculated by a spreadsheet app — compute
+the number in Python from the data cells instead of hunting for it.
+
+**Never `save()` a workbook opened with `data_only=True`.** That mode loads values
+in place of formulas, so saving writes the values back and every formula the user
+had is gone — silently, at `exitCode 0`, with an attachment that looks fine. A
+workbook you intend to save is always opened plainly:
+
+```python
+from openpyxl import load_workbook
+
+values = load_workbook("existing.xlsx", data_only=True)   # read numbers here
+wb = load_workbook("existing.xlsx")                       # edit and save this one
+```
+
+Read from `values`, write to `wb`, and save `wb`. One open, one job.
+
+That is reading in service of an edit. Reading for the *user* — a summary or an
+answer delivered as chat text — is its own flow with its own call shape: load
+`references/read.md`.
+
+## Errors
+
+- Never print the workbook's bytes or base64 — stdout is capped and the file
+  travels through `outputs`. A build call prints only a short summary line.
+  Never pass an absolute path to `save()`.
+- `attachment … not found in this chat` — `inputs` listed an id that is not in
+  this chat (often a copied placeholder). Only stage real ids from prior tool
+  results or `[Attached file …]` lines.
+- `an id-less input stages an uploaded image, and this path names a document` —
+  an `.xlsx` was staged with no `attachmentId`. Spreadsheets are always staged
+  by id.
+- `no uploaded image in this chat — attach an image or pass an attachmentId` —
+  an id-less input was sent when the user uploaded no image at all.
+- `FileNotFoundError: [Errno 44] No such file or directory` on a workbook you
+  saved in an earlier call means it was never staged: the working directory is
+  fresh every call. Add the file to `inputs` with its `attachmentId`.
+- A delivered workbook whose formulas have turned into blanks means it was opened
+  with `data_only=True` and then saved. Open a second, plain workbook to edit.
+- A delivered workbook whose table appears twice means the edit re-appended the
+  header and rows onto the staged sheet. An edit adds only what is new.
+- `AssertionError: a merged range at or below AT, or a formula — append instead …`
+  means a merged range sits at or below the insertion row, or the sheet has a formula
+  whose range `insert_rows` would not move. Append the row at the end instead and say
+  why in the reply.
+- `AssertionError: a merged range at or below the first deleted row, or a formula …`
+  is the same hazard on a delete, and has no safe fallback: say which rows you would
+  remove and ask the user how to handle the merges and formulas.
+- `AssertionError: no row matched …` means the delete found nothing, usually because
+  the compared values are strings on one side and numbers on the other. Diagnose the
+  match and rerun; do not remove the assert, because the workbook it would deliver
+  is the staged one unchanged.
+- Rows that disappeared from the wrong places mean the delete loop ran over
+  ascending indices. Collect the targets first and delete in reverse.
+- A row that renders unlike the rest of its column — `278` among `278.00`s — was
+  inserted without copying `number_format` from the row below it.
+- `'MergedCell' object attribute 'value' is read-only` means the write hit a merged
+  non-anchor cell — write the range's top-left cell instead.
+- `".xlsm" is not an allowed output type` means the run tried to deliver a
+  macro-enabled file — save as `.xlsx` and tell the user macros were not preserved.
+- `KeyError` on `wb["Sheet Name"]` — the sheet name does not exist; print
+  `wb.sheetnames` in the run that edits and pick from it.
+- `ModuleNotFoundError: No module named 'openpyxl'` — add
+  `["openpyxl==3.1.5"]` to `packages` and rerun. Never try to install it.
+- `ImportError: You must install Pillow to fetch image objects` means an image was
+  embedded without `"pillow"` in `packages` — openpyxl does not install it.
+- `FileNotFoundError` on a 32-character hex name means an attachment id was opened as
+  a path. The id belongs in `attachmentId`; open the `path` you chose.
+- On an `AttributeError` from openpyxl the API name is wrong, and on a `TypeError`
+  about missing positional arguments a required argument was left out — fix either
+  against this file's examples. Do not retry the same call, and do not switch to a
+  shell.
+
+## Finish
+
+When `exitCode` is `0` and `attachments` lists the `.xlsx`, stop tool use and
+answer with one line: file name + the `rows in / rows out` (or sheets) summary
+from stdout. Exactly one successful `exec` per request. If the result has
+`missingOutputs`, read stderr first — an `AssertionError` there means a guard
+stopped the save on purpose and its message names what to fix.

package/skills/excel/references/read.md

@@ -0,0 +1,99 @@
+# Reading a Workbook to Answer in Chat (openpyxl)
+
+When the user asks what an attached workbook *holds* — a summary, a question
+answered, specific values pulled out — the deliverable is your reply in the
+chat, not a file. This is a **read request**: exactly one `exec` call, staging
+the workbook in `inputs` and declaring **no `outputs`**, whose whole job is to
+print the sheets so you can read them in the result.
+
+## The exec call
+
+```json
+{
+  "language": "python",
+  "packages": ["openpyxl==3.1.5"],
+  "inputs": [{ "attachmentId": "<id from the [Attached file …] line>", "path": "existing.xlsx" }],
+  "maxOutputChars": 24000,
+  "command": "..."
+}
+```
+
+The id rules: copy it verbatim from the `[Attached file …]` line on the user's
+message or from the earlier `exec` result that produced the file, never invent
+one, never stage a workbook id-less (an id-less entry resolves to an uploaded
+*image*). If no id appears anywhere in the chat, ask the user to attach the
+file again. `maxOutputChars` raises the stdout cap so a full workbook comes
+back in one result; keep the sample's 24000. Declare no `outputs` — a read
+builds nothing.
+
+## The Read Program
+
+Prints every sheet under a `[Sheet]` marker, then its rows — one printed line
+per row:
+
+```python
+from openpyxl import load_workbook
+
+wb = load_workbook("existing.xlsx", data_only=True)
+for name in wb.sheetnames:
+    ws = wb[name]
+    print(f"[Sheet] {name} ({ws.max_row} rows)")
+    for row in ws.iter_rows(values_only=True):
+        print(" | ".join("" if v is None else str(v).replace("\n", " ") for v in row))
+```
+
+The `replace` is load-bearing: a multi-line cell (Alt+Enter in Excel) embeds
+`"\n"` in its value, and an embedded newline would split one row across two
+printed lines. Flattened, every printed line is exactly one sheet row.
+
+`data_only=True` is the right mode here: a formula cell prints the value the
+last spreadsheet app cached, or an empty field when the file was never
+recalculated (`None` prints as nothing). An empty field under a `Total` header
+is that, not missing data — say so, and when the answer needs the number, work
+it out from the data rows that did print.
+
+**You cannot summarize in the call that reads.** The words in `command` are
+fixed before the program runs, so one call cannot inform itself: any summary
+written into it was written blind — recalled or invented, not read. Python only
+*transports* the values; the summarizing happens in your reply, after the
+result comes back.
+
+## A Successful Read Ends Tool Use
+
+When the result prints the sheets, reply with the summary or the answer as chat
+text — when the user asked for the table in the chat, that reply is a markdown
+table built from the rows you read, never from memory. **Scale the reply to the
+workbook**: a summary is much shorter than what it summarizes — a small sheet
+earns a few sentences, and only a many-sheet workbook earns sections. Restating
+every row is not a summary. Do **not**:
+
+- call `exec` again to "re-check", "read more", or read the same workbook a
+  second time;
+- build a summary `.xlsx` the user never asked for — an unrequested file is a
+  failed turn, not a bonus.
+
+If stdout ends with `… [truncated]`, the workbook is longer than the cap:
+answer from what came back and say the answer covers the sheets up to that
+point. Do not rerun the read — it prints the same beginning again.
+
+If the user asks for the summary **as a file**, that is a read followed by a
+build: the read call above first, then one build call that writes the new
+workbook from the values you actually read (load `references/create.md` for the
+build). The read still declares no `outputs`.
+
+## Errors
+
+- `attachment … not found in this chat` — the id was invented or the file is
+  not attached. Re-copy the exact id; if none exists, ask the user to attach
+  the file again instead of retrying.
+- `an id-less input stages an uploaded image, and this path names a document` —
+  the workbook was staged with no `attachmentId`. Spreadsheets (`.xlsx`,
+  `.csv`, `.xlsm`) are always staged by id.
+- `FileNotFoundError: [Errno 44] No such file or directory` — the file was
+  never staged; the working directory is fresh every call. Add it to `inputs`
+  with its `attachmentId`.
+- `ModuleNotFoundError: No module named 'openpyxl'` — add
+  `["openpyxl==3.1.5"]` to `packages` and rerun. Never try to install it.
+- A formula cell that prints nothing is not a bug — the file was never
+  recalculated by a spreadsheet app. Compute the number from the data rows
+  instead of rerunning.

package/skills/github/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: github
+description: Search, read, and write GitHub repos, issues, and pull requests via the REST API.
+tools: [http_request]
+platform: [darwin, linux, win32, ios, android]
+credentials: [github_access_token]
+allow_list: [https://api.github.com/]
+---
+
+# GitHub
+
+Use `http_request` against `https://api.github.com` on every call, with `headers: {"Accept": "application/vnd.github+json"}`. The GitHub PAT credential is attached automatically to every `api.github.com` request — **never include an `auth` block**. Never fetch `github.com` web pages — they return HTML, not data; translate a pasted link to its API path instead (e.g. `github.com/{owner}/{repo}/pull/{n}` → `/repos/{owner}/{repo}/pulls/{n}`).
+
+```json
+{
+  "url": "https://api.github.com/search/issues?q=is:pr+is:open+repo:owner/repo&per_page=5",
+  "method": "GET",
+  "headers": { "Accept": "application/vnd.github+json" }
+}
+```
+
+## Reads
+
+- Search repos → `GET /search/repositories?q=...`
+- Search issues/PRs → `GET /search/issues?q=...` (always qualify with `is:pr` or `is:issue` — it returns both)
+- List issues → `GET /repos/{owner}/{repo}/issues?state=open` (items with a `pull_request` key are PRs, not issues)
+- List PRs → `GET /repos/{owner}/{repo}/pulls?state=open`
+- Read a file → `GET /repos/{owner}/{repo}/contents/{path}` (`content` is base64-encoded)
+- List a user's repos → `GET /user/repos?sort=updated`
+
+## Writes
+
+- Create an issue → `POST /repos/{owner}/{repo}/issues` with `body: {"title": "...", "body": "..."}`
+- Comment on an issue or PR → `POST /repos/{owner}/{repo}/issues/{n}/comments` with `body: {"body": "..."}` (PRs are issues for commenting — use the PR number on the issues endpoint)
+- Close or edit an issue → `PATCH /repos/{owner}/{repo}/issues/{n}` with `body: {"state": "closed"}`
+
+## Notes
+
+- Paginate with `per_page` (default small — 5, rarely above 30) and `page`; never fetch more than the request needs.
+- Ask for specific fields where the endpoint supports it, and summarize in plain language rather than echoing raw JSON — responses get truncated past 8KB.
+- **401** — token missing or revoked: tell the user to connect GitHub, don't retry. **404** on a resource the user linked directly usually means it's private, not nonexistent — search can't see private repos either. **403/429** mentioning rate limits — say so and stop.
+- Never print the token or the `Authorization` header, and don't claim a write succeeded without a successful response in this turn.

package/skills/gmail/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: gmail
+description: Read, search, send, and manage Gmail messages and labels via the Gmail REST API.
+aliases: [inbox, email+send, email+draft, email+reply, email+forward]
+tools: [http_request, gmail_send, gmail_draft]
+platform: [darwin, linux, win32]
+credentials: [gmail_access_token]
+allow_list: [https://gmail.googleapis.com/gmail/v1/users/me/]
+---
+
+# Gmail
+
+Use `gmail_send` to send, `gmail_draft` to draft, and `http_request` for everything else (list, search, get, labels, trash). The Gmail credential is attached automatically to every `gmail.googleapis.com` request — **never include an `auth` block**.
+
+## Prerequisites
+
+Gmail must be connected. Each Google skill is connected separately, with its
+own app and its own approval — connecting one grants nothing to the others. If
+credentials are missing, tell the user to connect Gmail from Settings, or to
+set the `gmail_access_token` credential.
+
+## Base URL
+
+`https://gmail.googleapis.com/gmail/v1/users/me`
+
+The host is `gmail.googleapis.com` — not `www.googleapis.com`. Send is at `/messages/send`, never `/send`.
+
+## Common Operations
+
+### List or search messages
+
+`messages.list` returns `{id, threadId}` pairs only — no subjects, no snippets. To summarize you need a follow-up `messages.get` per id. Use `q` for Gmail search syntax (`from:`, `subject:`, `is:unread`, `newer_than:7d`, `has:attachment`, `label:work`). Keep `maxResults` ≤ 10.
+
+```json
+{
+  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages",
+  "method": "GET",
+  "query": { "q": "is:unread newer_than:7d", "labelIds": "INBOX", "maxResults": 10 }
+}
+```
+
+### Get a message (metadata)
+
+For lists and summaries always use `format=metadata` — it skips the body and is far cheaper than `full`.
+
+```json
+{
+  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}",
+  "method": "GET",
+  "query": {
+    "format": "metadata",
+    "metadataHeaders": "Subject,From,To,Date,Message-ID,References"
+  }
+}
+```
+
+### Get a message (full body)
+
+Only when the user needs the content. The body is base64url-encoded in `payload.parts[].body.data` (or `payload.body.data`); decode it before presenting. Prefer the `text/plain` part over `text/html`.
+
+```json
+{
+  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}",
+  "method": "GET",
+  "query": { "format": "full" }
+}
+```
+
+### Send a message
+
+Use `gmail_send` with semantic args: `to` (array), `subject`, and `text` (or `html`). Optional: `cc`, `bcc`, `replyTo`. The tool builds the RFC 2822 message and base64url-encodes it — never construct `raw` yourself.
+
+```json
+{ "to": ["<RECIPIENT_EMAIL>"], "subject": "Subject line", "text": "Message body" }
+```
+
+If you supply both `text` and `html`, only `text` is sent — pick one.
+
+Confirm recipient, subject, and body with the user before sending. Report success only when the response contains a message `id`.
+
+### Draft a message
+
+Use `gmail_draft` with the same envelope as `gmail_send`.
+
+```json
+{ "to": ["<RECIPIENT_EMAIL>"], "subject": "Subject line", "text": "Draft body" }
+```
+
+### Reply to a message (preserves threading)
+
+A reply is `gmail_send` with the original's `threadId`, `inReplyTo`, and `references`. Without these Gmail starts a new thread.
+
+1. Get the original with `format=metadata` and headers `Message-ID,References,Subject,From,Reply-To`; capture its `threadId`.
+2. Send with `to` <- original From (or Reply-To), `subject` <- `Re: ` + original (don't double-prefix), `inReplyTo` <- original Message-ID, `references` <- original References then that Message-ID. Keep angle brackets.
+
+```json
+{
+  "to": ["<RECIPIENT_EMAIL>"],
+  "subject": "Re: Original subject",
+  "text": "Reply body",
+  "threadId": "{originalThreadId}",
+  "inReplyTo": "<msg-id@mail.gmail.com>",
+  "references": "<msg-id@mail.gmail.com>"
+}
+```
+
+### Modify labels (mark read, archive, star)
+
+System labels: `INBOX`, `UNREAD`, `STARRED`, `IMPORTANT`, `SPAM`, `TRASH`. Mark read = remove `UNREAD`; archive = remove `INBOX`; star = add `STARRED`.
+
+```json
+{
+  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}/modify",
+  "method": "POST",
+  "body": { "removeLabelIds": ["UNREAD", "INBOX"] }
+}
+```
+
+### Trash a message
+
+```json
+{
+  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}/trash",
+  "method": "POST"
+}
+```
+
+## Output Policy
+
+- Lists: up to 5 entries with subject, sender, and a human-readable date. Fetch full bodies only when asked.
+- Decode base64 message bodies before presenting; never include raw base64 blobs.
+- Modify/trash: state the user-facing effect ("marked 3 messages as read"), not the label diff.
+- Confirm destructive or outgoing actions (send, reply, trash) with the user first.
+
+## Common Mistakes
+
+- Using `www.googleapis.com` for Gmail, or building send/draft/reply through `http_request` instead of `gmail_send`/`gmail_draft`.
+- Treating `messages.list` results as if they had subjects — they need a follow-up `messages.get`.
+- Replying without `threadId` + `inReplyTo`/`references` — Gmail starts a new thread.
+- Sending a placeholder (`<RECIPIENT_EMAIL>`, `recipient@example.com`) — the runtime refuses these.
+- Inventing an address. The runtime refuses any recipient absent from the conversation and from earlier tool results; search Gmail or ask the user.
+- Including an `auth` block by hand — credentials attach automatically; a mistyped key breaks the request.