docs: refresh agent playbooks and project README

Point agents at the CLI safety rules, mailbox defaults, and the split usage/development guides.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -1,17 +1,31 @@
 # Gmail Reader
 
-Monorepo with a React + Vite + DaisyUI client, a Fastify API, and a Gmail push watcher. The API owns Google OAuth, stores tokens in SQLite, and calls the Gmail API with `gmail.readonly`. The browser only receives an HTTP-only session cookie. The watcher reuses those tokens, calls `users.watch`, and runs each new INBOX message through a handler pipeline.
+Monorepo with a React + Vite + DaisyUI client, a Fastify API, and a Gmail push watcher. The API owns Google OAuth, stores tokens in SQLite, and calls the Gmail API with `gmail.modify`. The browser only receives an HTTP-only session cookie (read-only inbox UI). The watcher reuses those tokens for Pub/Sub receipt processing and for the agent CLI (`npm run gmail`).
+
+Agent playbooks: [AGENTS.md](AGENTS.md), [docs/usage.md](docs/usage.md), [docs/development.md](docs/development.md).
 
 ## Prerequisites
 
 - Node.js 20+
 - A Google Cloud OAuth **Web application** client with:
-  - Scope: `https://www.googleapis.com/auth/gmail.readonly`
+  - Scope: `https://www.googleapis.com/auth/gmail.modify`
   - Authorized JavaScript origin: `https://oauth.0dev.web.id` (and `http://localhost:5173` for local)
   - Authorized redirect URIs:
     - `https://oauth.0dev.web.id/callback`
     - `http://localhost:5173/callback` (local; Vite proxies this to Fastify)
 
+### Change Google API permissions
+
+If you previously used `gmail.readonly`, update the OAuth consent screen and re-consent:
+
+1. **APIs & Services → Library**: Gmail API enabled.
+2. **OAuth consent screen** (or **Google Auth Platform → Data Access**): add `https://www.googleapis.com/auth/gmail.modify`; remove `gmail.readonly` if listed.
+3. While the app is **External + Testing**, list every mailbox under **Test users** (`gmail.modify` is sensitive).
+4. Keep the same Client ID / secret and redirect URIs.
+5. Restart the API and **sign in once per Gmail account** via the web UI so refresh tokens pick up the new scope.
+
+Full detail: [docs/development.md](docs/development.md#change-google-api-permissions-gmailmodify).
+
 ## Local development
 
 ```bash
@@ -37,7 +51,17 @@ npm run dev
 
 Vite proxies `/auth`, `/callback`, and `/api` to Fastify so the Google redirect stays on the same origin as the SPA.
 
-Sign in via the UI at least once so SQLite has a refresh token before starting the watcher.
+Sign in via the UI at least once so SQLite has a refresh token before starting the watcher or CLI.
+
+### Agent CLI (optional)
+
+```bash
+npm run gmail -- accounts
+npm run gmail -- list --query 'newer_than:7d'
+npm run gmail -- archive MESSAGE_ID --reason "noise"
+```
+
+See [docs/usage.md](docs/usage.md). Mutating commands require `--reason`. The CLI never sends mail.
 
 ## Production (one process)
 
@@ -92,13 +116,12 @@ oauth.0dev.web.id {
 }
 ```
 
-The watcher renews `users.watch` on startup and every 12 hours. Handlers run in sequence per new message: log the event, then fetch and log the message body. A handler may pass fields to the next one or `break` the chain.
+The watcher renews `users.watch` on startup and every 12 hours. New INBOX mail runs through match → parse → PocketBase (`spendings`). Details: [docs/development.md](docs/development.md).
 
 ## What it does
 
-- Sign in with Google (server-side authorization code flow)
-- List latest mail
-- Search with Gmail query syntax (`from:`, `subject:`, `newer_than:`, …)
-- Open a message and read decoded plain-text content
-- Watch INBOX via Gmail push (Pub/Sub) and run a sequential handler pipeline (log event, then fetch and log the message)
-- Watch INBOX via Gmail push (Pub/Sub) and run a sequential handler pipeline (log event, then fetch and log the message)
+- Sign in with Google (server-side authorization code flow; `gmail.modify`)
+- List / search / read mail in the web UI (read-only)
+- Multi-account tokens in SQLite with a configurable default mailbox
+- Agent CLI: list, read, summarize, labels, archive, label, draft, forward-as-draft, audit log
+- Watch INBOX via Gmail push (Pub/Sub) and parse e-receipts into PocketBase