@joe-broadhead/opencode-gws 0.0.4 → 0.0.6

package/skills/opencode-gws-recipes/SKILL.md

@@ -1,263 +1,92 @@
 ---
 name: opencode-gws-recipes
-description: Use when building a Gmail, Drive, Calendar, Docs, or Sheets request for gws_read or gws_plan.
+description: Load before the first gws_read or gws_plan for an everyday Google Workspace task; it has the ready request: unread or recent mail and who sent it, mail in a time window, replies and drafts, the next meetings or a week's schedule, finding, summarising, sharing or trashing Drive files and Google Docs, reading or appending Sheets rows, and the standup, meeting-prep and weekly-digest reports. Prefer it to any gws-* CLI skill.
 ---
 
 # Recipes
 
-These are exact requests for the everyday Gmail, Drive, Calendar, Docs, and Sheets tasks. Copy the shape. Replace the placeholder ids and text. Confirm the parameters with `gws_schema` when the task is not one of these.
-
-Pass `account` only when `gws_status` shows more than one account. `fields` is required on list and search. A change is `gws_plan`, then the commit tool of the **returned** category, with only `{ "planId": "<planId>" }`. Show the preview first.
-
-If `gws_catalog` says `executable` is false, do not call that id. Use `alternative`.
+Copy the shape and replace the ids. `opencode-gws` covers accounts, plan then commit, and errors. Each list example asks only for what the task needs; add a field when you need one.
 
 ## Gmail
 
-Unread inbox, read:
-
-```json
-{
-  "operation": "gmail.users.messages.list",
-  "params": { "userId": "me", "q": "is:unread", "maxResults": 10 },
-  "fields": "messages(id,threadId),nextPageToken"
-}
-```
-
-Mail between two times, read. `after:` and `before:` take Unix seconds; `newer_than:` and `older_than:` take only days, months, or years:
-
-```json
-{
-  "operation": "gmail.users.messages.list",
-  "params": { "userId": "me", "q": "after:1767225600 before:1767312000", "maxResults": 100 },
-  "fields": "messages(id,threadId),nextPageToken"
-}
-```
-
-Sender, subject, and date of one message, read, without the body:
-
-```json
-{
-  "operation": "gmail.users.messages.get",
-  "params": { "userId": "me", "id": "MESSAGE_ID", "format": "metadata", "metadataHeaders": ["From", "Subject"] },
-  "fields": "id,threadId,snippet,internalDate,payload/headers"
-}
-```
-
-One message, read. Prefer the helper when you want the text, not the raw payload:
+- **A time window.** `after:` and `before:` take Unix seconds, so compute them for the user's zone. 09:00 to 12:00 on 2026-11-03 at UTC+1 is `after:1793692800 before:1793703600`. `after:2026/11/03` means a whole day, and `newer_than:` takes only `d`, `m` or `y`.
+- **Who sent it.** Get each message with `format: "metadata"`, which skips the body. For the text, use `gmail.read` with `{"id": "...", "format": "text"}`. For a whole conversation, use `gmail.users.threads.get` with `format: "metadata"`.
+- **Exact unread count.** Read `gmail.users.labels.get`, not a list's `resultSizeEstimate`.
 
 ```json
-{
-  "operation": "gmail.read",
-  "input": { "id": "MESSAGE_ID", "format": "text" }
-}
+{ "operation": "gmail.users.messages.list", "params": { "userId": "me", "q": "after:1793692800 before:1793703600", "maxResults": 100 }, "fields": "messages(id),nextPageToken" }
 ```
 
-Triage, read:
-
 ```json
-{
-  "operation": "gmail.triage",
-  "input": { "max": 10, "query": "is:unread" }
-}
+{ "operation": "gmail.users.messages.get", "params": { "userId": "me", "id": "MESSAGE_ID", "format": "metadata", "metadataHeaders": ["From", "Subject", "Date"] }, "fields": "id,payload/headers" }
 ```
 
-Send. Plan, show the preview, then `gws_send`. Send does not offer Always.
-
-```json
-{
-  "operation": "gmail.send",
-  "input": {
-    "to": "person@example.com",
-    "subject": "Hello",
-    "body": "Hello"
-  }
-}
-```
-
-Reply. Same commit tool, `gws_send`:
-
-```json
-{
-  "operation": "gmail.reply",
-  "input": { "messageId": "MESSAGE_ID", "body": "Thanks" }
-}
-```
-
-The preview lists who the reply reaches: the sender, and for `gmail.reply-all` everyone else on the message. `to`, `cc` and `bcc` add recipients; `remove` leaves people out of a reply-all. `gmail.forward` takes `to`, `cc`, `bcc`, `body`, `attachments` and `noOriginalAttachments`. `gws_schema` lists every helper flag.
-
-## Drive
-
-Recent files, read:
-
 ```json
-{
-  "operation": "drive.files.list",
-  "params": { "q": "trashed = false", "pageSize": 20, "orderBy": "modifiedTime desc" },
-  "fields": "files(id,name,mimeType,modifiedTime),nextPageToken"
-}
+{ "operation": "gmail.users.labels.get", "params": { "userId": "me", "id": "INBOX" }, "fields": "messagesUnread,threadsUnread" }
 ```
 
-One file's metadata, read:
+- **Send, reply, forward.** Use `gmail.send` (`to`, `subject`, `body`, `cc`, `bcc`, `attachments`), or `gmail.reply`, `gmail.reply-all` or `gmail.forward` with `messageId`. Each plans as send. The preview lists everyone it reaches, including the sender a reply answers. Commit with `gws_send`.
+- **Draft.** Add `"draft": true`. It plans as write and reaches no one, so commit with `gws_write`. Sending the draft later is `gmail.users.drafts.send`, which is a send.
 
 ```json
-{
-  "operation": "drive.files.get",
-  "params": { "fileId": "FILE_ID" },
-  "fields": "id,name,mimeType,modifiedTime"
-}
-```
-
-Create a file, write. Plan, then `gws_write`. An upload path must be absolute and inside an allowed read root. `gws_schema` shows the upload field.
-
-```json
-{
-  "operation": "drive.files.create",
-  "body": { "name": "Notes.txt", "mimeType": "text/plain" }
-}
-```
-
-Move to trash. The plan category is **delete**, even if the manifest says write. Commit with `gws_delete`, not `gws_write`.
-
-```json
-{
-  "operation": "drive.files.update",
-  "params": { "fileId": "FILE_ID" },
-  "body": { "trashed": true }
-}
-```
-
-Share with one person. Plan category is share. Commit with `gws_share`. Share does not offer Always.
-
-```json
-{
-  "operation": "drive.permissions.create",
-  "params": { "fileId": "FILE_ID" },
-  "body": { "type": "user", "role": "reader", "emailAddress": "person@example.com" }
-}
+{ "operation": "gmail.reply", "input": { "messageId": "MESSAGE_ID", "body": "Thanks, Thursday works.", "draft": true } }
 ```
 
 ## Calendar
 
-Today's agenda, read:
+- **Next meetings.** Always set `timeMin` to now. Without it, `orderBy: "startTime"` returns the calendar's oldest events. `timeMin` also returns events still running, such as all-day ones (`start.date`), so ask for more than you need (`maxResults: 10`) and skip those when the user means meetings. `singleEvents: true` expands recurring meetings.
+- **A range, such as next week.** Set `timeMin` to Monday 00:00 and `timeMax` to the next Monday 00:00, both with the user's offset. Put `timeZone` in `fields` to learn the calendar's zone without another call. Count each event on its local start date. All-day events have `start.date`, not `start.dateTime`.
+- **The helper.** `calendar.agenda` takes `today`, `tomorrow`, `week` or `days`, plus `timezone`. It is smaller than a full events list.
 
 ```json
-{
-  "operation": "calendar.agenda",
-  "input": { "today": true }
-}
+{ "operation": "calendar.events.list", "params": { "calendarId": "primary", "timeMin": "2026-11-05T14:30:00+01:00", "singleEvents": true, "orderBy": "startTime", "maxResults": 10 }, "fields": "timeZone,items(summary,start,end,htmlLink),nextPageToken" }
 ```
 
-Events on the primary calendar, read:
-
 ```json
-{
-  "operation": "calendar.events.list",
-  "params": { "calendarId": "primary", "maxResults": 10, "singleEvents": true, "orderBy": "startTime" },
-  "fields": "items(id,summary,start,end),nextPageToken"
-}
+{ "operation": "calendar.agenda", "input": { "week": true, "timezone": "Europe/Amsterdam" } }
 ```
 
-Create an event that does not email anyone. Plan category is write. Commit with `gws_write`.
+- **An event.** `calendar.events.insert` with `calendarId: "primary"` and a body with `summary`, `start` and `end`. It plans as write. With `sendUpdates: "all"` it emails the guests and plans as send.
 
-```json
-{
-  "operation": "calendar.events.insert",
-  "params": { "calendarId": "primary" },
-  "body": {
-    "summary": "Standup",
-    "start": { "dateTime": "2026-11-02T09:00:00+01:00" },
-    "end": { "dateTime": "2026-11-02T09:15:00+01:00" }
-  }
-}
-```
+## Drive and Docs
 
-Create or move an event that emails attendees (`sendUpdates` of `all` or `externalOnly`; prefer it to the deprecated `sendNotifications`, which counts as a send too). The plan category is **send**. Commit with `gws_send`.
+- **Search.** Drive's `q` uses clauses joined by `and`: `name contains 'budget'`, `fullText contains 'offsite'`, `'me' in owners` and `trashed = false`. A Doc is `mimeType = 'application/vnd.google-apps.document'`, and a Sheet is `mimeType = 'application/vnd.google-apps.spreadsheet'`. For "the one I edited", order by `modifiedByMeTime desc`; otherwise use `modifiedTime desc`.
 
 ```json
-{
-  "operation": "calendar.events.insert",
-  "params": { "calendarId": "primary", "sendUpdates": "all" },
-  "body": {
-    "summary": "Standup",
-    "start": { "dateTime": "2026-11-02T09:00:00+01:00" },
-    "end": { "dateTime": "2026-11-02T09:15:00+01:00" }
-  }
-}
+{ "operation": "drive.files.list", "params": { "q": "mimeType = 'application/vnd.google-apps.document' and trashed = false", "orderBy": "modifiedByMeTime desc", "pageSize": 1 }, "fields": "files(id,name,modifiedTime,webViewLink,ownedByMe,capabilities/canTrash)" }
 ```
 
-## Docs
-
-Read a document:
+- **A Doc's text.** Read it with this mask; the `table` branch keeps text inside tables. The full document is several times larger. `drive.files.export` is not a read: it writes a file to disk after a prompt, so don't use it to read a Doc.
 
 ```json
-{
-  "operation": "docs.documents.get",
-  "params": { "documentId": "DOCUMENT_ID" }
-}
+{ "operation": "docs.documents.get", "params": { "documentId": "DOCUMENT_ID" }, "fields": "title,body/content(paragraph/elements/textRun/content,table/tableRows/tableCells/content/paragraph/elements/textRun/content)" }
 ```
 
-Create a document, write. Plan, then `gws_write`.
+- **Edit a Doc.** `docs.documents.batchUpdate` with `{"requests": [{"insertText": {"location": {"index": 1}, "text": "..."}}]}`. Index 1 is the start of the body. It plans as write.
+- **Trash (the bin).** Use `drive.files.update` with `"body": {"trashed": true}`. It plans as delete, so commit with `gws_delete`. The owner can restore it from the trash for 30 days. People it is shared with keep access until it is permanently deleted. Only the owner can trash a file (on a shared drive, an organizer or file organizer, with `supportsAllDrives: true`). Ask for `ownedByMe` and `capabilities/canTrash` in the list, as above, so you need no extra call. `drive.files.delete` is a permanent delete that removes everyone's access, so never use it for "bin" or "trash".
 
 ```json
-{
-  "operation": "docs.documents.create",
-  "body": { "title": "Notes" }
-}
+{ "operation": "drive.files.update", "params": { "fileId": "FILE_ID" }, "body": { "trashed": true } }
 ```
 
-Insert text, write. Plan, then `gws_write`.
-
-```json
-{
-  "operation": "docs.documents.batchUpdate",
-  "params": { "documentId": "DOCUMENT_ID" },
-  "body": {
-    "requests": [
-      { "insertText": { "location": { "index": 1 }, "text": "Hello" } }
-    ]
-  }
-}
-```
+- **Share.** `drive.permissions.create` with `fileId` and a body such as `{"type": "user", "role": "reader", "emailAddress": "..."}`. It plans as share.
+- **Upload.** `drive.files.create` with a `body` (`name`, `mimeType`) and the plugin's own top-level `"upload": {"path": "/absolute/file.pdf", "mime": "application/pdf"}`. `gws_schema` doesn't show `upload`.
 
 ## Sheets
 
-Read a range. The helper is enough for a rectangular range:
+- **Read.** `sheets.read` with `{"spreadsheet": "ID", "range": "A1:D20"}`. A range without a sheet name reads the first sheet, so don't guess a name such as `Sheet1`.
+- **Append rows.** `sheets.spreadsheets.values.append` with `range: "A1"`, `valueInputOption: "USER_ENTERED"` and `{"values": [[...]]}`. It plans as write.
 
-```json
-{
-  "operation": "sheets.read",
-  "input": { "spreadsheet": "SPREADSHEET_ID", "range": "Sheet1!A1:D20" }
-}
-```
-
-The method, when you need the raw values resource:
-
-```json
-{
-  "operation": "sheets.spreadsheets.values.get",
-  "params": { "spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:D20" }
-}
-```
+## Reports
 
-Append rows, write. Plan, then `gws_write`.
+`workflow.standup-report`, `workflow.meeting-prep` and `workflow.weekly-digest` are reads. Run them with `gws_read`, and `input: {"format": "json"}` for structured data.
 
 ```json
-{
-  "operation": "sheets.spreadsheets.values.append",
-  "params": {
-    "spreadsheetId": "SPREADSHEET_ID",
-    "range": "Sheet1!A1",
-    "valueInputOption": "USER_ENTERED"
-  },
-  "body": { "values": [["a", "b"]] }
-}
+{ "operation": "workflow.standup-report", "input": { "format": "json" } }
 ```
 
-Create a spreadsheet, write. Plan, then `gws_write`.
+Login activity is Admin SDK Reports. It needs an account for a Workspace admin with the Reports privilege. Any other account gets `ADMIN_PRIVILEGE_REQUIRED`, which signing in again as the same account won't fix.
 
 ```json
-{
-  "operation": "sheets.spreadsheets.create",
-  "body": { "properties": { "title": "Notes" } }
-}
+{ "operation": "admin-reports.activities.list", "params": { "userKey": "all", "applicationName": "login", "startTime": "2026-11-04T14:30:00Z" }, "fields": "items(actor/email,id/time,events/name),nextPageToken" }
 ```

package/skills/opencode-gws-admin/SKILL.md

@@ -1,97 +0,0 @@
----
-name: opencode-gws-admin
-description: Load only when the user asks for admin reports, Apps Script, Workspace Events, Model Armor, or a workflow helper.
-opencode/autoinvoke: false
----
-
-# High-risk Workspace services
-
-This skill is not loaded automatically. Use it only when the user asked for admin reports, Apps Script, Workspace Events, Model Armor, or a workflow helper.
-
-Search with `gws_catalog` and check `gws_schema` before you call. If `executable` is false, do not call that id. Deploy and watch never run. A helper with no adapter cannot run; use `alternative` when the catalog names one.
-
-## Admin gate
-
-An operation whose category is `admin` needs all of these before `gws_plan` will accept it:
-
-1. `admin.enabled` is true, which is the default.
-2. The service is in `admin.allowedServices` (the default list is the services that have an admin-class entry).
-3. The plan includes a non-empty `reason` when `admin.requireReason` is true, which is the default.
-
-Then commit with `gws_admin` and only `{ "planId": "<planId>" }`. `gws_admin` asks every time. It does not offer Always. A user deny hides the tool.
-
-A read on one of these services is still a read: `gws_read`, no admin gate. A write that is not category `admin` still uses `gws_write` and the normal ask.
-
-Plugin policy cannot allow an admin call. A policy rule can only deny.
-
-## Admin reports
-
-Read-only at both access levels. The sign-in still needs the admin report scopes from the auth doc, and the account must be a Workspace admin with the Reports privilege: otherwise every call fails with `ADMIN_PRIVILEGE_REQUIRED`, which signing in again as the same account does not fix.
-
-Activity list, read. `fields` is required because this is a list:
-
-```json
-{
-  "operation": "admin-reports.activities.list",
-  "params": { "userKey": "all", "applicationName": "login" },
-  "fields": "items(id,actor,events),nextPageToken"
-}
-```
-
-Watching an activity feed is category `admin`, not a read. Plan it only when the user asked, with a reason, then commit with `gws_admin`:
-
-```json
-{
-  "operation": "admin-reports.activities.watch",
-  "params": { "userKey": "all", "applicationName": "login" },
-  "reason": "The user asked to watch login activity."
-}
-```
-
-`gws_schema` shows the watch body. Do not invent a channel.
-
-## Apps Script
-
-Read a project:
-
-```json
-{
-  "operation": "script.projects.get",
-  "params": { "scriptId": "SCRIPT_ID" }
-}
-```
-
-Creating a project is a write. Plan, then `gws_write`. Deployments and running a script never run. If catalog marks an id not executable, stop and tell the user.
-
-## Workspace Events
-
-Most subscription methods never run. A status read can:
-
-```json
-{
-  "operation": "events.operations.get",
-  "params": { "name": "operations/OPERATION_ID" }
-}
-```
-
-## Model Armor
-
-Read and write requests `https://www.googleapis.com/auth/cloud-platform` for Model Armor; Read-only requests nothing for it. The Model Armor helpers cannot run. Do not invent a call. Tell the user, and use `gws_catalog` if they still want a Discovery method.
-
-## Workflow
-
-These three helpers are reads. They need the account to enable `workflow`, which uses the Gmail, Calendar, Tasks, and Drive scopes.
-
-```json
-{ "operation": "workflow.meeting-prep", "input": {} }
-```
-
-```json
-{ "operation": "workflow.standup-report", "input": {} }
-```
-
-```json
-{ "operation": "workflow.weekly-digest", "input": {} }
-```
-
-Other workflow helpers cannot run. Use the alternative `gws_catalog` names, and commit with that method's category tool.