docs(gmail): document filter creation support

README.md

@@ -1154,6 +1154,7 @@ Supported delivery modes:
 1. Create a Google Cloud project with the Gmail API enabled
 2. Create OAuth2 credentials (Desktop application type) and download the JSON file
 3. Run `flynn gmail-auth` to complete the OAuth2 flow and store the refresh token
+   - Requests scopes for both mailbox reads and filter management (`gmail.readonly` + `gmail.settings.basic`)
 
 For Pub/Sub delivery (push/pull), also enable the Pub/Sub API and create:
 - A topic (e.g. `projects/your-project/topics/gmail-push`)
@@ -1208,6 +1209,17 @@ Pull mode uses Application Default Credentials (e.g. `GOOGLE_APPLICATION_CREDENT
 | `output.channel` | yes | Channel name to route the response (e.g. `telegram`) |
 | `output.peer` | yes | Peer/chat ID on the output channel |
 
+### Gmail Tools
+
+When `automation.gmail.enabled: true`, Flynn registers Gmail tools:
+
+- `gmail.list` — list recent messages by label
+- `gmail.search` — query messages with Gmail search syntax
+- `gmail.read` — fetch full message body by ID
+- `gmail.filter.create` — create Gmail filters (criteria + actions like archive/label/forward)
+
+`gmail.filter.create` requires a token with `gmail.settings.basic`. If your token was created before this scope was added, re-run `flynn gmail-auth`.
+
 ### Template Variables
 
 | Variable | Description |