docs: add Google Calendar section and new-tool checklist

Add GCal tools setup guide to README (prerequisites, config, fields).
Add gmail-auth, gcal-auth, setup to the CLI commands table. Add
"Adding a New Tool" checklist to CLAUDE.md covering the full wiring
chain including the TUI registration gotcha.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -64,6 +64,9 @@ Flynn provides a full CLI via the `flynn` binary (or `npx tsx src/cli/index.ts`
 | `flynn doctor` | Validate config and check system health |
 | `flynn config` | Show resolved configuration (secrets redacted) |
 | `flynn completion <shell>` | Generate shell completions (bash, zsh, fish) |
+| `flynn setup` | Interactive setup wizard |
+| `flynn gmail-auth` | Authenticate with Gmail via OAuth2 |
+| `flynn gcal-auth` | Authenticate with Google Calendar via OAuth2 |
 
 ### Examples
 
@@ -417,6 +420,36 @@ Push notifications arrive at `POST /gmail/push` on the gateway HTTP server (bypa
 | `{{id}}` | Gmail message ID |
 | `{{labels}}` | Comma-separated label names |
 
+## Google Calendar Tools
+
+Query Google Calendar events from within conversations. Provides three tools: `calendar.today` (today's agenda), `calendar.list` (date range), and `calendar.search` (full-text search).
+
+### Prerequisites
+
+1. A Google Cloud project with the **Calendar API** enabled
+2. OAuth2 credentials (Desktop application type) — the same credentials file used for Gmail works
+3. Run `flynn gcal-auth` to complete the OAuth2 flow and store the refresh token
+
+### Configuration
+
+```yaml
+automation:
+  gcal:
+    enabled: true
+    credentials_file: ~/.config/flynn/gmail-credentials.json
+    token_file: ~/.config/flynn/gcal-token.json   # Default location
+    calendar_ids: [primary]                        # Calendar IDs to query
+```
+
+### Google Calendar Config Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `enabled` | no | Enable the calendar tools (default: `false`) |
+| `credentials_file` | yes | Path to Google OAuth2 credentials JSON |
+| `token_file` | no | Path to stored OAuth2 refresh token (default: `~/.config/flynn/gcal-token.json`) |
+| `calendar_ids` | no | Calendar IDs available for queries (default: `[primary]`) |
+
 ## Vector Memory Search
 
 The memory system supports hybrid search combining keyword matching with semantic vector similarity. When embeddings are enabled, `memory.search` uses both approaches and merges results with configurable weighting.