invos 1.0.0

package/kit/.agents/skills/popular-web-designs/templates/zapier.md

@@ -0,0 +1,341 @@
+# Design System: Zapier
+
+
+> **Hermes Agent — Implementation Notes**
+>
+> The original site uses proprietary fonts. For self-contained HTML output, use these CDN substitutes:
+> - **Primary:** `Inter` | **Mono:** `system monospace stack`
+> - **Font stack (CSS):** `font-family: 'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;`
+> - **Mono stack (CSS):** `font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;`
+> ```html
+> <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+> ```
+> Use `write_file` to create HTML, serve via `generative-widgets` skill (cloudflared tunnel).
+> Verify visual accuracy with `browser_vision` after generating.
+
+## 1. Visual Theme & Atmosphere
+
+Zapier's website radiates warm, approachable professionalism. It rejects the cold monochrome minimalism of developer tools in favor of a cream-tinted canvas (`#fffefb`) that feels like unbleached paper -- the digital equivalent of a well-organized notebook. The near-black (`#201515`) text has a faint reddish-brown warmth, creating an atmosphere more human than mechanical. This is automation designed to feel effortless, not technical.
+
+The typographic system is a deliberate interplay of two distinct personalities. **Degular Display** -- a geometric, wide-set display face -- handles hero-scale headlines at 56-80px with medium weight (500) and extraordinarily tight line-heights (0.90), creating headlines that compress vertically like stacked blocks. **Inter** serves as the workhorse for everything else, from section headings to body text and navigation, with fallbacks to Helvetica and Arial. **GT Alpina**, an elegant thin-weight serif with aggressive negative letter-spacing (-1.6px to -1.92px), makes occasional appearances for softer editorial moments. This three-font system gives Zapier the ability to shift register -- from bold and punchy (Degular) to clean and functional (Inter) to refined and literary (GT Alpina).
+
+The brand's signature orange (`#ff4f00`) is unmistakable -- a vivid, saturated red-orange that sits precisely between traffic-cone urgency and sunset warmth. It's used sparingly but decisively: primary CTA buttons, active state underlines, and accent borders. Against the warm cream background, this orange creates a color relationship that feels energetic without being aggressive.
+
+**Key Characteristics:**
+- Warm cream canvas (`#fffefb`) instead of pure white -- organic, paper-like warmth
+- Near-black with reddish undertone (`#201515`) -- text that breathes rather than dominates
+- Degular Display for hero headlines at 0.90 line-height -- compressed, impactful, modern
+- Inter as the universal UI font across all functional typography
+- GT Alpina for editorial accents -- thin-weight serif with extreme negative tracking
+- Zapier Orange (`#ff4f00`) as the single accent -- vivid, warm, sparingly applied
+- Warm neutral palette: borders (`#c5c0b1`), muted text (`#939084`), surface tints (`#eceae3`)
+- 8px base spacing system with generous padding on CTAs (20px 24px)
+- Border-forward design: `1px solid` borders in warm grays define structure over shadows
+
+## 2. Color Palette & Roles
+
+### Primary
+- **Zapier Black** (`#201515`): Primary text, headings, dark button backgrounds. A warm near-black with reddish undertones -- never cold.
+- **Cream White** (`#fffefb`): Page background, card surfaces, light button fills. Not pure white; the yellowish warmth is intentional.
+- **Off-White** (`#fffdf9`): Secondary background surface, subtle alternate tint. Nearly indistinguishable from cream white but creates depth.
+
+### Brand Accent
+- **Zapier Orange** (`#ff4f00`): Primary CTA buttons, active underline indicators, accent borders. The signature color -- vivid and warm.
+
+### Neutral Scale
+- **Dark Charcoal** (`#36342e`): Secondary text, footer text, border color for strong dividers. A warm dark gray-brown with 70% opacity variant.
+- **Warm Gray** (`#939084`): Tertiary text, muted labels, timestamp-style content. Mid-range with greenish-warm undertone.
+- **Sand** (`#c5c0b1`): Primary border color, hover state backgrounds, divider lines. The backbone of Zapier's structural elements.
+- **Light Sand** (`#eceae3`): Secondary button backgrounds, light borders, subtle card surfaces.
+- **Mid Warm** (`#b5b2aa`): Alternate border tone, used on specific span elements.
+
+### Interactive
+- **Orange CTA** (`#ff4f00`): Primary action buttons and active tab underlines.
+- **Dark CTA** (`#201515`): Secondary dark buttons with sand hover state.
+- **Light CTA** (`#eceae3`): Tertiary/ghost buttons with sand hover.
+- **Link Default** (`#201515`): Standard link color, matching body text.
+- **Hover Underline**: Links remove `text-decoration: underline` on hover (inverse pattern).
+
+### Overlay & Surface
+- **Semi-transparent Dark** (`rgba(45, 45, 46, 0.5)`): Overlay button variant, backdrop-like elements.
+- **Pill Surface** (`#fffefb`): White pill buttons with sand borders.
+
+### Shadows & Depth
+- **Inset Underline** (`rgb(255, 79, 0) 0px -4px 0px 0px inset`): Active tab indicator -- orange underline using inset box-shadow.
+- **Hover Underline** (`rgb(197, 192, 177) 0px -4px 0px 0px inset`): Inactive tab hover -- sand-colored underline.
+
+## 3. Typography Rules
+
+### Font Families
+- **Display**: `Degular Display` -- wide geometric display face for hero headlines
+- **Primary**: `Inter`, with fallbacks: `Helvetica, Arial`
+- **Editorial**: `GT Alpina` -- thin-weight serif for editorial moments
+- **System**: `Arial` -- fallback for form elements and system UI
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|------|--------|-------------|----------------|-------|
+| Display Hero XL | Degular Display | 80px (5.00rem) | 500 | 0.90 (tight) | normal | Maximum impact, compressed block |
+| Display Hero | Degular Display | 56px (3.50rem) | 500 | 0.90-1.10 (tight) | 0-1.12px | Primary hero headlines |
+| Display Hero SM | Degular Display | 40px (2.50rem) | 500 | 0.90 (tight) | normal | Smaller hero variant |
+| Display Button | Degular Display | 24px (1.50rem) | 600 | 1.00 (tight) | 1px | Large CTA button text |
+| Section Heading | Inter | 48px (3.00rem) | 500 | 1.04 (tight) | normal | Major section titles |
+| Editorial Heading | GT Alpina | 48px (3.00rem) | 250 | normal | -1.92px | Thin editorial headlines |
+| Editorial Sub | GT Alpina | 40px (2.50rem) | 300 | 1.08 (tight) | -1.6px | Editorial subheadings |
+| Sub-heading LG | Inter | 36px (2.25rem) | 500 | normal | -1px | Large sub-sections |
+| Sub-heading | Inter | 32px (2.00rem) | 400 | 1.25 (tight) | normal | Standard sub-sections |
+| Sub-heading MD | Inter | 28px (1.75rem) | 500 | normal | normal | Medium sub-headings |
+| Card Title | Inter | 24px (1.50rem) | 600 | normal | -0.48px | Card headings |
+| Body Large | Inter | 20px (1.25rem) | 400-500 | 1.00-1.20 (tight) | -0.2px | Feature descriptions |
+| Body Emphasis | Inter | 18px (1.13rem) | 600 | 1.00 (tight) | normal | Emphasized body text |
+| Body | Inter | 16px (1.00rem) | 400-500 | 1.20-1.25 | -0.16px | Standard reading text |
+| Body Semibold | Inter | 16px (1.00rem) | 600 | 1.16 (tight) | normal | Strong labels |
+| Button | Inter | 16px (1.00rem) | 600 | normal | normal | Standard buttons |
+| Button SM | Inter | 14px (0.88rem) | 600 | normal | normal | Small buttons |
+| Caption | Inter | 14px (0.88rem) | 500 | 1.25-1.43 | normal | Labels, metadata |
+| Caption Upper | Inter | 14px (0.88rem) | 600 | normal | 0.5px | Uppercase section labels |
+| Micro | Inter | 12px (0.75rem) | 600 | 0.90-1.33 | 0.5px | Tiny labels, often uppercase |
+| Micro SM | Inter | 13px (0.81rem) | 500 | 1.00-1.54 | normal | Small metadata text |
+
+### Principles
+- **Three-font system, clear roles**: Degular Display commands attention at hero scale only. Inter handles everything functional. GT Alpina adds editorial warmth sparingly.
+- **Compressed display**: Degular at 0.90 line-height creates vertically compressed headline blocks that feel modern and architectural.
+- **Weight as hierarchy signal**: Inter uses 400 (reading), 500 (navigation/emphasis), 600 (headings/CTAs). Degular uses 500 (display) and 600 (buttons).
+- **Uppercase for labels**: Section labels (like "01 / Colors") and small categorization use `text-transform: uppercase` with 0.5px letter-spacing.
+- **Negative tracking for elegance**: GT Alpina uses -1.6px to -1.92px letter-spacing for its thin-weight editorial headlines.
+
+## 4. Component Stylings
+
+### Buttons
+
+**Primary Orange**
+- Background: `#ff4f00`
+- Text: `#fffefb`
+- Padding: 8px 16px
+- Radius: 4px
+- Border: `1px solid #ff4f00`
+- Use: Primary CTA ("Start free with email", "Sign up free")
+
+**Primary Dark**
+- Background: `#201515`
+- Text: `#fffefb`
+- Padding: 20px 24px
+- Radius: 8px
+- Border: `1px solid #201515`
+- Hover: background shifts to `#c5c0b1`, text to `#201515`
+- Use: Large secondary CTA buttons
+
+**Light / Ghost**
+- Background: `#eceae3`
+- Text: `#36342e`
+- Padding: 20px 24px
+- Radius: 8px
+- Border: `1px solid #c5c0b1`
+- Hover: background shifts to `#c5c0b1`, text to `#201515`
+- Use: Tertiary actions, filter buttons
+
+**Pill Button**
+- Background: `#fffefb`
+- Text: `#36342e`
+- Padding: 0px 16px
+- Radius: 20px
+- Border: `1px solid #c5c0b1`
+- Use: Tag-like selections, filter pills
+
+**Overlay Semi-transparent**
+- Background: `rgba(45, 45, 46, 0.5)`
+- Text: `#fffefb`
+- Radius: 20px
+- Hover: background becomes fully opaque `#2d2d2e`
+- Use: Video play buttons, floating actions
+
+**Tab / Navigation (Inset Shadow)**
+- Background: transparent
+- Text: `#201515`
+- Padding: 12px 16px
+- Shadow: `rgb(255, 79, 0) 0px -4px 0px 0px inset` (active orange underline)
+- Hover shadow: `rgb(197, 192, 177) 0px -4px 0px 0px inset` (sand underline)
+- Use: Horizontal tab navigation
+
+### Cards & Containers
+- Background: `#fffefb`
+- Border: `1px solid #c5c0b1` (warm sand border)
+- Radius: 5px (standard), 8px (featured)
+- No shadow elevation by default -- borders define containment
+- Hover: subtle border color intensification
+
+### Inputs & Forms
+- Background: `#fffefb`
+- Text: `#201515`
+- Border: `1px solid #c5c0b1`
+- Radius: 5px
+- Focus: border color shifts to `#ff4f00` (orange)
+- Placeholder: `#939084`
+
+### Navigation
+- Clean horizontal nav on cream background
+- Zapier logotype left-aligned, 104x28px
+- Links: Inter 16px weight 500, `#201515` text
+- CTA: Orange button ("Start free with email")
+- Tab navigation uses inset box-shadow underline technique
+- Mobile: hamburger collapse
+
+### Image Treatment
+- Product screenshots with `1px solid #c5c0b1` border
+- Rounded corners: 5-8px
+- Dashboard/workflow screenshots prominent in feature sections
+- Light gradient backgrounds behind hero content
+
+### Distinctive Components
+
+**Workflow Integration Cards**
+- Display connected app icons in pairs
+- Arrow or connection indicator between apps
+- Sand border containment
+- Inter weight 500 for app names
+
+**Stat Counter**
+- Large display number using Inter 48px weight 500
+- Muted description below in `#36342e`
+- Used for social proof metrics
+
+**Social Proof Icons**
+- Circular icon buttons: 14px radius
+- Sand border: `1px solid #c5c0b1`
+- Used for social media follow links in footer
+
+## 5. Layout Principles
+
+### Spacing System
+- Base unit: 8px
+- Scale: 1px, 4px, 6px, 8px, 10px, 12px, 16px, 20px, 24px, 32px, 40px, 48px, 56px, 64px, 72px
+- CTA buttons use generous padding: 20px 24px for large, 8px 16px for standard
+- Section padding: 64px-80px vertical
+
+### Grid & Container
+- Max content width: approximately 1200px
+- Hero: centered single-column with large top padding
+- Feature sections: 2-3 column grids for integration cards
+- Full-width sand-bordered dividers between sections
+- Footer: multi-column dark background (`#201515`)
+
+### Whitespace Philosophy
+- **Warm breathing room**: Generous vertical spacing between sections (64px-80px), but content areas are relatively dense -- Zapier packs information efficiently within its cream canvas.
+- **Architectural compression**: Degular Display headlines at 0.90 line-height compress vertically, contrasting with the open spacing around them.
+- **Section rhythm**: Cream background throughout, with sections separated by sand-colored borders rather than background color changes.
+
+### Border Radius Scale
+- Tight (3px): Small inline spans
+- Standard (4px): Buttons (orange CTA), tags, small elements
+- Content (5px): Cards, links, general containers
+- Comfortable (8px): Featured cards, large buttons, tabs
+- Social (14px): Social icon buttons, pill-like elements
+- Pill (20px): Play buttons, large pill buttons, floating actions
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Flat (Level 0) | No shadow | Page background, text blocks |
+| Bordered (Level 1) | `1px solid #c5c0b1` | Standard cards, containers, inputs |
+| Strong Border (Level 1b) | `1px solid #36342e` | Dark dividers, emphasized sections |
+| Active Tab (Level 2) | `rgb(255, 79, 0) 0px -4px 0px 0px inset` | Active tab underline (orange) |
+| Hover Tab (Level 2b) | `rgb(197, 192, 177) 0px -4px 0px 0px inset` | Hover tab underline (sand) |
+| Focus (Accessibility) | `1px solid #ff4f00` outline | Focus ring on interactive elements |
+
+**Shadow Philosophy**: Zapier deliberately avoids traditional shadow-based elevation. Structure is defined almost entirely through borders -- warm sand (`#c5c0b1`) borders for standard containment, dark charcoal (`#36342e`) borders for emphasis. The only shadow-like technique is the inset box-shadow used for tab underlines, where a `0px -4px 0px 0px inset` shadow creates a bottom-bar indicator. This border-first approach keeps the design grounded and tangible rather than floating.
+
+### Decorative Depth
+- Orange inset underline on active tabs creates visual "weight" at the bottom of elements
+- Sand hover underlines provide preview states without layout shifts
+- No background gradients in main content -- the cream canvas is consistent
+- Footer uses full dark background (`#201515`) for contrast reversal
+
+## 7. Do's and Don'ts
+
+### Do
+- Use Degular Display exclusively for hero-scale headlines (40px+) with 0.90 line-height for compressed impact
+- Use Inter for all functional UI -- navigation, body text, buttons, labels
+- Apply warm cream (`#fffefb`) as the background, never pure white
+- Use `#201515` for text, never pure black -- the reddish warmth matters
+- Keep Zapier Orange (`#ff4f00`) reserved for primary CTAs and active state indicators
+- Use sand (`#c5c0b1`) borders as the primary structural element instead of shadows
+- Apply generous button padding (20px 24px) for large CTAs to match Zapier's spacious button style
+- Use inset box-shadow underlines for tab navigation rather than border-bottom
+- Apply uppercase with 0.5px letter-spacing for section labels and micro-categorization
+
+### Don't
+- Don't use Degular Display for body text or UI elements -- it's display-only
+- Don't use pure white (`#ffffff`) or pure black (`#000000`) -- Zapier's palette is warm-shifted
+- Don't apply box-shadow elevation to cards -- use borders instead
+- Don't scatter Zapier Orange across the UI -- it's reserved for CTAs and active states
+- Don't use tight padding on large CTA buttons -- Zapier's buttons are deliberately spacious
+- Don't ignore the warm neutral system -- borders should be `#c5c0b1`, not gray
+- Don't use GT Alpina for functional UI -- it's an editorial accent at thin weights only
+- Don't apply positive letter-spacing to GT Alpina -- it uses aggressive negative tracking (-1.6px to -1.92px)
+- Don't use rounded pill shapes (9999px) for primary buttons -- pills are for tags and social icons
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile Small | <450px | Tight single column, reduced hero text |
+| Mobile | 450-600px | Standard mobile, stacked layout |
+| Mobile Large | 600-640px | Slight horizontal breathing room |
+| Tablet Small | 640-680px | 2-column grids begin |
+| Tablet | 680-768px | Card grids expand |
+| Tablet Large | 768-991px | Full card grids, expanded padding |
+| Desktop Small | 991-1024px | Desktop layout initiates |
+| Desktop | 1024-1280px | Full layout, maximum content width |
+| Large Desktop | >1280px | Centered with generous margins |
+
+### Touch Targets
+- Large CTA buttons: 20px 24px padding (comfortable 60px+ height)
+- Standard buttons: 8px 16px padding
+- Navigation links: 16px weight 500 with adequate spacing
+- Social icons: 14px radius circular buttons
+- Tab items: 12px 16px padding
+
+### Collapsing Strategy
+- Hero: Degular 80px display scales to 40-56px on smaller screens
+- Navigation: horizontal links + CTA collapse to hamburger menu
+- Feature cards: 3-column grid to 2-column to single-column stacked
+- Integration workflow illustrations: maintain aspect ratio, may simplify
+- Footer: multi-column dark section collapses to stacked
+- Section spacing: 64-80px reduces to 40-48px on mobile
+
+### Image Behavior
+- Product screenshots maintain sand border treatment at all sizes
+- Integration app icons maintain fixed sizes within responsive containers
+- Hero illustrations scale proportionally
+- Full-width sections maintain edge-to-edge treatment
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Primary CTA: Zapier Orange (`#ff4f00`)
+- Background: Cream White (`#fffefb`)
+- Heading text: Zapier Black (`#201515`)
+- Body text: Dark Charcoal (`#36342e`)
+- Border: Sand (`#c5c0b1`)
+- Secondary surface: Light Sand (`#eceae3`)
+- Muted text: Warm Gray (`#939084`)
+
+### Example Component Prompts
+- "Create a hero section on cream background (`#fffefb`). Headline at 56px Degular Display weight 500, line-height 0.90, color `#201515`. Subtitle at 20px Inter weight 400, line-height 1.20, color `#36342e`. Orange CTA button (`#ff4f00`, 4px radius, 8px 16px padding, white text) and dark button (`#201515`, 8px radius, 20px 24px padding, white text)."
+- "Design a card: cream background (`#fffefb`), `1px solid #c5c0b1` border, 5px radius. Title at 24px Inter weight 600, letter-spacing -0.48px, `#201515`. Body at 16px weight 400, `#36342e`. No box-shadow."
+- "Build a tab navigation: transparent background. Inter 16px weight 500, `#201515` text. Active tab: `box-shadow: rgb(255, 79, 0) 0px -4px 0px 0px inset`. Hover: `box-shadow: rgb(197, 192, 177) 0px -4px 0px 0px inset`. Padding 12px 16px."
+- "Create navigation: cream sticky header (`#fffefb`). Inter 16px weight 500 for links, `#201515` text. Orange pill CTA 'Start free with email' right-aligned (`#ff4f00`, 4px radius, 8px 16px padding)."
+- "Design a footer with dark background (`#201515`). Text `#fffefb`. Links in `#c5c0b1` with hover to `#fffefb`. Multi-column layout. Social icons as 14px-radius circles with sand borders."
+
+### Iteration Guide
+1. Always use warm cream (`#fffefb`) background, never pure white -- the warmth defines Zapier
+2. Borders (`1px solid #c5c0b1`) are the structural backbone -- avoid shadow elevation
+3. Zapier Orange (`#ff4f00`) is the only accent color; everything else is warm neutrals
+4. Three fonts, strict roles: Degular Display (hero), Inter (UI), GT Alpina (editorial)
+5. Large CTA buttons need generous padding (20px 24px) -- Zapier buttons feel spacious
+6. Tab navigation uses inset box-shadow underlines, not border-bottom
+7. Text is always warm: `#201515` for dark, `#36342e` for body, `#939084` for muted
+8. Uppercase labels at 12-14px with 0.5px letter-spacing for section categorization

package/kit/.agents/skills/productivity/DESCRIPTION.md

@@ -0,0 +1,3 @@
+---
+description: Skills for document creation, presentations, spreadsheets, and other productivity workflows.
+---

package/kit/.agents/skills/productivity/google-workspace/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: google-workspace
+description: "Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python."
+version: 1.1.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+required_credential_files:
+  - path: google_token.json
+    description: Google OAuth2 token (created by setup script)
+  - path: google_client_secret.json
+    description: Google OAuth2 client credentials (downloaded from Google Cloud Console)
+metadata:
+  hermes:
+    tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]
+    homepage: https://github.com/NousResearch/hermes-agent
+    related_skills: [himalaya]
+---
+
+# Google Workspace
+
+Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When `gws` is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.
+
+## References
+
+- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)
+
+## Scripts
+
+- `scripts/setup.py` — OAuth2 setup (run once to authorize)
+- `scripts/google_api.py` — compatibility wrapper CLI. It prefers `gws` for operations when available, while preserving Hermes' existing JSON output contract.
+
+## First-Time Setup
+
+The setup is fully non-interactive — you drive it step by step so it works
+on CLI, Telegram, Discord, or any platform.
+
+Define a shorthand first:
+
+```bash
+GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
+```
+
+### Step 0: Check if already set up
+
+```bash
+$GSETUP --check
+```
+
+If it prints `AUTHENTICATED`, skip to Usage — setup is already done.
+
+### Step 1: Triage — ask the user what they need
+
+Before starting OAuth setup, ask the user TWO questions:
+
+**Question 1: "What Google services do you need? Just email, or also
+Calendar/Drive/Sheets/Docs?"**
+
+- **Email only** → They don't need this skill at all. Use the `himalaya` skill
+  instead — it works with a Gmail App Password (Settings → Security → App
+  Passwords) and takes 2 minutes to set up. No Google Cloud project needed.
+  Load the himalaya skill and follow its setup instructions.
+
+- **Email + Calendar** → Continue with this skill, but use
+  `--services email,calendar` during auth so the consent screen only asks for
+  the scopes they actually need.
+
+- **Calendar/Drive/Sheets/Docs only** → Continue with this skill and use a
+  narrower `--services` set like `calendar,drive,sheets,docs`.
+
+- **Full Workspace access** → Continue with this skill and use the default
+  `all` service set.
+
+**Question 2: "Does your Google account use Advanced Protection (hardware
+security keys required to sign in)? If you're not sure, you probably don't
+— it's something you would have explicitly enrolled in."**
+
+- **No / Not sure** → Normal setup. Continue below.
+- **Yes** → Their Workspace admin must add the OAuth client ID to the org's
+  allowed apps list before Step 4 will work. Let them know upfront.
+
+### Step 2: Create OAuth credentials (one-time, ~5 minutes)
+
+Tell the user:
+
+> You need a Google Cloud OAuth client. This is a one-time setup:
+>
+> 1. Create or select a project:
+>    https://console.cloud.google.com/projectselector2/home/dashboard
+> 2. Enable the required APIs from the API Library:
+>    https://console.cloud.google.com/apis/library
+>    Enable: Gmail API, Google Calendar API, Google Drive API,
+>    Google Sheets API, Google Docs API, People API
+> 3. Create the OAuth client here:
+>    https://console.cloud.google.com/apis/credentials
+>    Credentials → Create Credentials → OAuth 2.0 Client ID
+> 4. Application type: "Desktop app" → Create
+> 5. If the app is still in Testing, add the user's Google account as a test user here:
+>    https://console.cloud.google.com/auth/audience
+>    Audience → Test users → Add users
+> 6. Download the JSON file and tell me the file path
+>
+> Important Hermes CLI note: if the file path starts with `/`, do NOT send only the bare path as its own message in the CLI, because it can be mistaken for a slash command. Send it in a sentence instead, like:
+> `The JSON file path is: /home/user/Downloads/client_secret_....json`
+
+Once they provide the path:
+
+```bash
+$GSETUP --client-secret /path/to/client_secret.json
+```
+
+If they paste the raw client ID / client secret values instead of a file path,
+write a valid Desktop OAuth JSON file for them yourself, save it somewhere
+explicit (for example `~/Downloads/hermes-google-client-secret.json`), then run
+`--client-secret` against that file.
+
+### Step 3: Get authorization URL
+
+Use the service set chosen in Step 1. Examples:
+
+```bash
+$GSETUP --auth-url --services email,calendar --format json
+$GSETUP --auth-url --services calendar,drive,sheets,docs --format json
+$GSETUP --auth-url --services all --format json
+```
+
+This returns JSON with an `auth_url` field and also saves the exact URL to
+`~/.hermes/google_oauth_last_url.txt`.
+
+Agent rules for this step:
+- Extract the `auth_url` field and send that exact URL to the user as a single line.
+- Tell the user that the browser will likely fail on `http://localhost:1` after approval, and that this is expected.
+- Tell them to copy the ENTIRE redirected URL from the browser address bar.
+- If the user gets `Error 403: access_denied`, send them directly to `https://console.cloud.google.com/auth/audience` to add themselves as a test user.
+
+### Step 4: Exchange the code
+
+The user will paste back either a URL like `http://localhost:1/?code=4/0A...&scope=...`
+or just the code string. Either works. The `--auth-url` step stores a temporary
+pending OAuth session locally so `--auth-code` can complete the PKCE exchange
+later, even on headless systems:
+
+```bash
+$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
+```
+
+If `--auth-code` fails because the code expired, was already used, or came from
+an older browser tab, it now returns a fresh `fresh_auth_url`. In that case,
+immediately send the new URL to the user and have them retry with the newest
+browser redirect only.
+
+### Step 5: Verify
+
+```bash
+$GSETUP --check
+```
+
+Should print `AUTHENTICATED`. Setup is complete — token refreshes automatically from now on.
+
+### Notes
+
+- Token is stored at `~/.hermes/google_token.json` and auto-refreshes.
+- Pending OAuth session state/verifier are stored temporarily at `~/.hermes/google_oauth_pending.json` until exchange completes.
+- If `gws` is installed, `google_api.py` points it at the same `~/.hermes/google_token.json` credentials file. Users do not need to run a separate `gws auth login` flow.
+- To revoke: `$GSETUP --revoke`
+
+## Usage
+
+All commands go through the API script. Set `GAPI` as a shorthand:
+
+```bash
+GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
+```
+
+### Gmail
+
+```bash
+# Search (returns JSON array with id, from, subject, date, snippet)
+$GAPI gmail search "is:unread" --max 10
+$GAPI gmail search "from:boss@company.com newer_than:1d"
+$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
+
+# Read full message (returns JSON with body text)
+$GAPI gmail get MESSAGE_ID
+
+# Send
+$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
+$GAPI gmail send --to user@example.com --subject "Report" --body "<h1>Q4</h1><p>Details...</p>" --html
+$GAPI gmail send --to user@example.com --subject "Hello" --from '"Research Agent" <user@example.com>' --body "Message text"
+
+# Reply (automatically threads and sets In-Reply-To)
+$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
+$GAPI gmail reply MESSAGE_ID --from '"Support Bot" <user@example.com>' --body "Thanks"
+
+# Labels
+$GAPI gmail labels
+$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
+$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
+```
+
+### Calendar
+
+```bash
+# List events (defaults to next 7 days)
+$GAPI calendar list
+$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
+
+# Create event (ISO 8601 with timezone required)
+$GAPI calendar create --summary "Team Standup" --start 2026-03-01T10:00:00-06:00 --end 2026-03-01T10:30:00-06:00
+$GAPI calendar create --summary "Lunch" --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z --location "Cafe"
+$GAPI calendar create --summary "Review" --start 2026-03-01T14:00:00Z --end 2026-03-01T15:00:00Z --attendees "alice@co.com,bob@co.com"
+
+# Delete event
+$GAPI calendar delete EVENT_ID
+```
+
+### Drive
+
+```bash
+# Search existing files
+$GAPI drive search "quarterly report" --max 10
+$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
+
+# Get metadata for a single file
+$GAPI drive get FILE_ID
+
+# Upload a local file (auto-detects MIME type)
+$GAPI drive upload /path/to/report.pdf
+$GAPI drive upload /path/to/image.png --name "Logo.png" --parent FOLDER_ID
+
+# Download (binary files download as-is; Google-native files export to a
+# sensible default — Docs→pdf, Sheets→csv, Slides→pdf, Drawings→png)
+$GAPI drive download FILE_ID
+$GAPI drive download DOC_ID --output ~/doc.pdf
+$GAPI drive download DOC_ID --export-mime text/plain --output ~/doc.txt
+
+# Create a folder
+$GAPI drive create-folder "Reports"
+$GAPI drive create-folder "Q4" --parent FOLDER_ID
+
+# Share
+$GAPI drive share FILE_ID --email alice@example.com --role reader
+$GAPI drive share FILE_ID --email alice@example.com --role writer --notify
+$GAPI drive share FILE_ID --type anyone --role reader        # anyone with link
+$GAPI drive share FILE_ID --type domain --domain example.com --role reader
+
+# Delete — defaults to trash (reversible). Use --permanent to skip the trash.
+$GAPI drive delete FILE_ID
+$GAPI drive delete FILE_ID --permanent
+```
+
+### Contacts
+
+```bash
+$GAPI contacts list --max 20
+```
+
+### Sheets
+
+```bash
+# Create a new spreadsheet
+$GAPI sheets create --title "Q4 Budget"
+$GAPI sheets create --title "Inventory" --sheet-name "Stock"
+
+# Read
+$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
+
+# Write
+$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
+
+# Append rows
+$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
+```
+
+### Docs
+
+```bash
+# Read
+$GAPI docs get DOC_ID
+
+# Create a new Doc (optionally seeded with body text)
+$GAPI docs create --title "Meeting Notes"
+$GAPI docs create --title "Draft" --body "First paragraph..."
+
+# Append text to the end of an existing Doc
+$GAPI docs append DOC_ID --text "Additional content to append"
+```
+
+## Output Format
+
+All commands return JSON. Parse with `jq` or read directly. Key fields:
+
+- **Gmail search**: `[{id, threadId, from, to, subject, date, snippet, labels}]`
+- **Gmail get**: `{id, threadId, from, to, subject, date, labels, body}`
+- **Gmail send/reply**: `{status: "sent", id, threadId}`
+- **Calendar list**: `[{id, summary, start, end, location, description, htmlLink}]`
+- **Calendar create**: `{status: "created", id, summary, htmlLink}`
+- **Drive search**: `[{id, name, mimeType, modifiedTime, webViewLink}]`
+- **Drive get**: `{id, name, mimeType, modifiedTime, size, webViewLink, parents, owners}`
+- **Drive upload**: `{status: "uploaded", id, name, mimeType, webViewLink}`
+- **Drive download**: `{status: "downloaded", id, name, path, mimeType}`
+- **Drive create-folder**: `{status: "created", id, name, webViewLink}`
+- **Drive share**: `{status: "shared", permissionId, fileId, role, type}`
+- **Drive delete**: `{status: "trashed" | "deleted", fileId, permanent}`
+- **Contacts list**: `[{name, emails: [...], phones: [...]}]`
+- **Sheets get**: `[[cell, cell, ...], ...]`
+- **Sheets create**: `{status: "created", spreadsheetId, title, spreadsheetUrl}`
+- **Docs create**: `{status: "created", documentId, title, url}`
+- **Docs append**: `{status: "appended", documentId, inserted_at, characters}`
+
+## Rules
+
+1. **Never send email, create/delete calendar events, delete Drive files, share files, or modify Docs/Sheets without confirming with the user first.** Show what will be done (recipients, file IDs, content, share role) and ask for approval. For `drive delete`, prefer the default trash (reversible) over `--permanent`.
+2. **Check auth before first use** — run `setup.py --check`. If it fails, guide the user through setup.
+3. **Use the Gmail search syntax reference** for complex queries — load it with `skill_view("google-workspace", file_path="references/gmail-search-syntax.md")`.
+4. **Calendar times must include timezone** — always use ISO 8601 with offset (e.g., `2026-03-01T10:00:00-06:00`) or UTC (`Z`).
+5. **Respect rate limits** — avoid rapid-fire sequential API calls. Batch reads when possible.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `NOT_AUTHENTICATED` | Run setup Steps 2-5 above |
+| `REFRESH_FAILED` | Token revoked or expired — redo Steps 3-5 |
+| `HttpError 403: Insufficient Permission` | Missing API scope — `$GSETUP --revoke` then redo Steps 3-5 |
+| `AUTHENTICATED (partial)` or "Token missing scopes" | New write capabilities (Drive write/delete, Docs create/edit) require re-authorization. `$GSETUP --revoke` then redo Steps 3-5 to grant the upgraded scopes. |
+| `HttpError 403: Access Not Configured` | API not enabled — user needs to enable it in Google Cloud Console |
+| `ModuleNotFoundError` | Run `$GSETUP --install-deps` |
+| Advanced Protection blocks auth | Workspace admin must allowlist the OAuth client ID |
+
+## Revoking Access
+
+```bash
+$GSETUP --revoke
+```