@@ -0,0 +1,171 @@
1+---
2+name: gws-google-assistant-cookbook
3+description: Use when the user wants help with Gmail, Google Drive, Calendar, or general Google Workspace tasks via the gws CLI in this repository. Covers auth checks, safe inbox inspection, Drive listing/search, message/thread retrieval, and practical command recipes.
4+---
5+
6+You are working in a repository where `gws` is the preferred interface for Google Workspace.
7+
8+## Goal
9+
10+Help the user manage Gmail, Drive, and Calendar through `gws` with minimal friction. Prefer executing `gws` commands and summarizing results over giving generic advice.
11+
12+## Before starting
13+
14+1. Check authentication first:
15+
16+```bash
17+gws auth status
18+```
19+
20+2. If not authenticated or token is invalid, stop and tell the user to run:
21+
22+```bash
23+gws auth login --services drive,gmail,calendar
24+```
25+
26+3. Do not expose secrets or decrypted credentials.
27+ - Never run `gws auth export` unless the user explicitly asks.
28+ - Never print `client_secret.json`, refresh tokens, or raw authorization headers.
29+
30+## Working style
31+
32+- Use `gws` commands directly.
33+- Prefer small, verifiable reads before broad operations.
34+- When inspecting email, start with metadata (`list`, then `get` with metadata or snippets) before fetching full raw content.
35+- When the user asks for "recent emails", default to inbox messages for `userId=me`.
36+- When the user asks for Drive files, start with `files list` and a small `pageSize`.
37+- Summarize findings clearly and briefly.
38+
39+## Gmail cookbook
40+
41+### Recent inbox messages
42+
43+```bash
44+gws gmail users messages list --params '{"userId":"me","maxResults":10,"labelIds":["INBOX"]}'
45+```
46+
47+Then fetch metadata for selected message IDs:
48+
49+```bash
50+gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID","format":"metadata","metadataHeaders":["From","To","Subject","Date"]}'
51+```
52+
53+Useful fields:
54+- `payload.headers`
55+- `snippet`
56+- `labelIds`
57+- `internalDate`
58+
59+### Search mail
60+
61+Examples:
62+
63+```bash
64+gws gmail users messages list --params '{"userId":"me","maxResults":10,"q":"from:noreply@github.com newer_than:7d"}'
65+```
66+
67+```bash
68+gws gmail users messages list --params '{"userId":"me","maxResults":20,"q":"is:unread in:inbox"}'
69+```
70+
71+### Read a thread
72+
73+```bash
74+gws gmail users threads get --params '{"userId":"me","id":"THREAD_ID"}'
75+```
76+
77+### Mark messages read
78+
79+```bash
80+gws gmail users messages modify \
81+ --params '{"userId":"me","id":"MESSAGE_ID"}' \
82+ --json '{"removeLabelIds":["UNREAD"]}'
83+```
84+
85+### Add a star
86+
87+```bash
88+gws gmail users messages modify \
89+ --params '{"userId":"me","id":"MESSAGE_ID"}' \
90+ --json '{"addLabelIds":["STARRED"]}'
91+```
92+
93+### Trash a message
94+
95+```bash
96+gws gmail users messages trash --params '{"userId":"me","id":"MESSAGE_ID"}'
97+```
98+
99+Use destructive mail actions only when the user clearly asks.
100+
101+## Drive cookbook
102+
103+### List recent files
104+
105+```bash
106+gws drive files list --params '{"pageSize":10,"fields":"files(id,name,mimeType,modifiedTime,webViewLink)"}'
107+```
108+
109+### Search Drive
110+
111+```bash
112+gws drive files list --params '{"pageSize":10,"q":"name contains \"invoice\" and trashed = false","fields":"files(id,name,mimeType,modifiedTime,webViewLink)"}'
113+```
114+
115+### Get file details
116+
117+```bash
118+gws drive files get --params '{"fileId":"FILE_ID","fields":"id,name,mimeType,owners,modifiedTime,webViewLink,size"}'
119+```
120+
121+### Export a Google Doc
122+
123+```bash
124+gws drive files export --params '{"fileId":"FILE_ID","mimeType":"text/plain"}' --output ./document.txt
125+```
126+
127+### Upload a local file
128+
129+```bash
130+gws drive files create \
131+ --params '{"uploadType":"multipart"}' \
132+ --json '{"name":"example.txt"}' \
133+ --upload ./example.txt
134+```
135+
136+## Calendar cookbook
137+
138+### List upcoming events on primary calendar
139+
140+```bash
141+gws calendar events list --params '{"calendarId":"primary","maxResults":10,"singleEvents":true,"orderBy":"startTime","timeMin":"2026-01-01T00:00:00Z"}'
142+```
143+
144+For "upcoming events", set `timeMin` to the current timestamp.
145+
146+## Troubleshooting
147+
148+### Inspect auth state
149+
150+```bash
151+gws auth status
152+```
153+
154+### Re-login with required services
155+
156+```bash
157+gws auth login --services drive,gmail,calendar
158+```
159+
160+### Read-only login
161+
162+```bash
163+gws auth login --services drive,gmail,calendar --readonly
164+```
165+
166+## Response guidelines
167+
168+- Prefer executing the command and reporting the result.
169+- Include the exact `gws` command when it helps the user repeat the action.
170+- Do not dump large JSON unless asked; extract the fields the user cares about.
171+- If an operation may modify or delete user data, confirm intent unless the user explicitly requested that exact action.