@vellumai/assistant 0.4.3 → 0.4.4

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -34,6 +34,7 @@ These are hard prohibitions. Violating any of these produces that unmistakable "
 - **NEVER** make all text the same size and weight — establish clear hierarchy with at least 3 distinct levels
 - **NEVER** use a pure white (`#fff`) or pure dark (`#000`/`#0a0a0a`) background — ALWAYS tint it to match the domain (cream `#FEFCF9` for lifestyle, sage `#F0F5F0` for nature, cool gray `#F5F7FA` for finance, warm blush `#FDF6F3` for wellness)
 - **NEVER** leave clickable elements without hover AND active states
+- **NEVER** hand-code SVG/CSS charts (lines, bars, sparklines, gauges) — ALWAYS use `vellum.widgets.lineChart()`, `.barChart()`, `.sparkline()`, or `.progressRing()`. They handle bounds, clipping, scaling, and dark mode correctly. Hand-coded charts invariably overflow and bleed into adjacent elements.
 - **ALWAYS** use emoji as visual identifiers in stat cards, list items, and navigation — they replace icon libraries and add instant personality (🍎 for food, 🔥 for streaks, 💰 for money, 🌿 for plants)
 - **ALWAYS** apply the accent-word pattern in hero headings — color ONE key word or phrase in the accent color: "Your <span style='color: var(--accent)'>Week</span> in Motion"
 - **ALWAYS** include a contextual/personalized header — a greeting ("Good morning"), date ("Saturday, Feb 15"), or welcome ("Welcome back, Alex") — not just the app title
@@ -92,6 +93,23 @@ These are hard prohibitions. Violating any of these produces that unmistakable "
 Copy-paste-ready CSS techniques. All work in the sandboxed WebView with no external dependencies.
 
 ### Animated Gradient Background
+
+Choose **one** of the following color variants (do not combine both):
+
+**Variant A — Warm pastels (light, airy feel):**
+```css
+body {
+  background: linear-gradient(-45deg, #fef3c7, #fce7f3, #e0e7ff, #d1fae5);
+  background-size: 400% 400%;
+  animation: gradientShift 15s ease infinite;
+}
+@keyframes gradientShift {
+  0%, 100% { background-position: 0% 50%; }
+  50% { background-position: 100% 50%; }
+}
+```
+
+**Variant B — Dark jewel tones (deep, rich feel):**
 ```css
 body {
   background: linear-gradient(-45deg, #0f172a, #1e1b4b, #172554, #0c4a6e);
@@ -108,9 +126,9 @@ body {
 ```css
 body {
   background:
-    radial-gradient(ellipse at 20% 50%, color-mix(in srgb, var(--v-violet-500) 15%, transparent) 0%, transparent 50%),
-    radial-gradient(ellipse at 80% 20%, color-mix(in srgb, var(--v-indigo-500) 12%, transparent) 0%, transparent 50%),
-    radial-gradient(ellipse at 50% 80%, color-mix(in srgb, var(--v-emerald-500) 8%, transparent) 0%, transparent 50%),
+    radial-gradient(ellipse at 20% 50%, color-mix(in srgb, var(--v-rose-400) 15%, transparent) 0%, transparent 50%),
+    radial-gradient(ellipse at 80% 20%, color-mix(in srgb, var(--v-amber-400) 12%, transparent) 0%, transparent 50%),
+    radial-gradient(ellipse at 50% 80%, color-mix(in srgb, var(--v-teal-400) 10%, transparent) 0%, transparent 50%),
     var(--v-bg);
 }
 ```
@@ -161,7 +179,7 @@ body::before {
 ### Gradient Text
 ```css
 .gradient-text {
-  background: linear-gradient(135deg, var(--v-violet-500), var(--v-indigo-400));
+  background: linear-gradient(135deg, var(--v-rose-500), var(--v-amber-400));
   -webkit-background-clip: text;
   -webkit-text-fill-color: transparent;
   background-clip: text;
@@ -348,7 +366,7 @@ document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
 .accent-word { color: var(--accent, var(--v-accent)); }
 /* Gradient variant — use .v-gradient-text from the design system, or customize: */
 .accent-gradient {
-  background: linear-gradient(135deg, var(--accent, var(--v-violet-500)), var(--v-indigo-400));
+  background: linear-gradient(135deg, var(--accent, var(--v-rose-500)), var(--v-amber-400));
   -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;
 }
 ```
@@ -1021,7 +1039,9 @@ async function handleBulk(action) {
 }
 ```
 
-**Presentation slideshow** — multi-slide deck with 8 layout variants (title, stats, bullets, quote, comparison, visual, timeline, closing). Use the slideshow widget for presentations, pitch decks, and multi-slide educational content. The model provides slide content; the widget handles navigation, transitions, and keyboard support.
+**Presentation slideshow** — multi-slide deck with 8 layout variants (title, stats, bullets, quote, comparison, visual, timeline, closing). Use the slideshow widget for presentations, pitch decks, and multi-slide educational content. The model provides slide content; the widget handles navigation, transitions, and keyboard support. Never tell the user how to navigate slides — the UI is self-explanatory.
+
+> **For comprehensive slide design guidelines, see the "Presentation Slide Design" section below.** The following HTML shows the structural template for all 8 layout types.
 
 ```html
 <!DOCTYPE html>
@@ -1159,7 +1179,7 @@ document.addEventListener('DOMContentLoaded', function() {
 - **Use widgets** for standard patterns — tables, metrics, timelines, notifications, presentations
 - **Use custom HTML** for novel or creative UIs — games, art tools, unique dashboards
 - **Mix freely** — widgets compose well together and with custom elements
-- Always prioritize the ideal user experience over using the widget library
+- Always prioritize the ideal user experience over using the widget library — EXCEPT for charts: always use `vellum.widgets.*` chart functions (lineChart, barChart, sparkline, progressRing) instead of hand-coding SVG/CSS charts. They handle overflow clipping, bounds, scaling, and dark mode. Hand-coded charts break layouts.
 
 #### Advanced techniques
 
@@ -1332,7 +1352,25 @@ Both `ui_show` and `app_create` support a `preview` object for an inline chat pr
 }
 ```
 
-**With `app_create`:**
+**With `app_create` (image URL icon):**
+```json
+{
+  "name": "Microsoft Overview",
+  "schema_json": "{}",
+  "html": "...",
+  "preview": {
+    "title": "Microsoft",
+    "subtitle": "3 Slides",
+    "icon": "https://www.microsoft.com/favicon.ico",
+    "metrics": [
+      { "label": "Founded", "value": "1975" },
+      { "label": "Market Cap", "value": "$2.98T" }
+    ]
+  }
+}
+```
+
+**With `app_create` (emoji icon):**
 ```json
 {
   "name": "Expense Tracker",
@@ -1349,7 +1387,7 @@ Both `ui_show` and `app_create` support a `preview` object for an inline chat pr
 }
 ```
 
-Preview fields: `title` (required), `subtitle`, `description`, `icon` (emoji), `metrics` (up to 3 key-value pills). When `app_create` is called with `auto_open: true` (the default), the preview is forwarded through `app_open` automatically.
+Preview fields: `title` (required), `subtitle`, `description`, `icon`, `metrics` (up to 3 key-value pills). The `icon` field accepts an emoji or an image URL. **Prefer an image URL whenever you have a relevant one** — logos, favicons, product images, headshots, flags, album art, or any image you encountered during research. The preview card renders image URLs as a thumbnail automatically. Fall back to emoji only when there is no natural image. When `app_create` is called with `auto_open: true` (the default), the preview is forwarded through `app_open` automatically.
 
 ### 6. Handle Iteration
 
@@ -1490,7 +1528,105 @@ Before delivering any app, mentally verify these 10 items — they cover the gap
 | `.v-metric-card .v-metric-icon` | Emoji icon in metric cards | Place emoji `<span>` with `.v-metric-icon` inside `.v-metric-card` |
 | `.v-slideshow` | Presentation slide deck with transitions | `.v-slide` (`.active`), `.v-slide-label`, `.v-slide-title`, `.v-slide-body`, `.v-slide-stats`, `.v-slide-stat`, `.v-slide-quote` — init with `vellum.widgets.slideshow()` |
 
-Every app should include: search/filter, toast notifications for all CRUD operations, `window.vellum.confirm()` for destructive actions, staggered page-load animation, card hover effects, and skeleton loading states.
+Every app should include: search/filter, toast notifications for all CRUD operations, `window.vellum.confirm()` for destructive actions, staggered page-load animation, card hover effects, and skeleton loading states. (These requirements do not apply to presentation slide decks — see "Presentation Slide Design" below.)
+
+## Presentation Slide Design
+
+### Slide Design Philosophy
+
+- **One idea per slide** — each slide communicates a single concept, not a cluster of related points
+- **Glanceable, not readable** — a slide should be understood in 3 seconds; dense text belongs in documents, not presentations
+- **Visual storytelling arc** — open strong, build context, create emotional resonance, close with impact
+- **Cinematic quality bar** — every deck should feel at home in a startup pitch, TED talk, or Apple keynote
+- **The slide is the visual** — don't describe what the audience should imagine; show it through layout, color, and typography
+
+### What App Rules to Skip for Slides
+
+The general app design checklist does NOT apply to slide decks. Specifically skip:
+
+- Contextual header/greeting ("Good morning, Alex") — slides are not dashboards
+- Search/filter, pill toggles, suggestion chips — slides are not interactive apps
+- Toast notifications, confirm dialogs, form validation — no CRUD in slides
+- Data bridge API / `window.vellum.data` — slides are static content
+- Skeleton loading states — slides render instantly
+- Mandatory trust/status pill badge — use only when slide content calls for it (e.g., a "verified" badge on a stats slide)
+- Mandatory emoji stat cards — use when they strengthen the message, skip when they clutter
+- The app Pre-Ship Design Checklist — use the Slide Pre-Ship Checklist instead
+
+### Slide Typography
+
+- **Title slides:** `clamp(2rem, 5vw, 3rem)`, weight 800 — much larger than app text
+- **Body text:** `clamp(1rem, 2.5vw, 1.25rem)` — larger than app body (14px); keep to 2–3 sentences max
+- **Stat values:** `clamp(1.75rem, 4vw, 2.5rem)` — big numbers are the most impactful element on any slide
+- **Accent-word technique is ESSENTIAL** — even more than apps, every heading should color one key word with the accent color
+- **Contrast is everything** — near-white on dark, near-black on light; no washed-out middle ground
+- **Never go below 15px** for any visible text — if it doesn't fit, cut words, don't shrink font
+
+### Slide Color & Visual Treatment
+
+- **Bold, full-bleed backgrounds** — warm cream, blush pink, soft lavender, deep navy, rich purple, dark emerald; vary light and dark across the deck
+- **Animated gradient backgrounds** are ideal for title and closing slides — use `background-size: 400% 400%` with CSS animation
+- **Domain-matched palettes still apply**, just executed more dramatically — a finance deck is navy/gold, a health deck is teal/white
+- **One accent color used sparingly** — titles, stat borders, label dots, CTA buttons; never more than one accent
+- **Glassmorphism works well** for slide overlays on visual/immersive slides — `backdrop-filter: blur()` with semi-transparent bg
+- **Full-screen immersion:** `.v-slideshow` should use `border-radius: 0; min-height: 100vh` for edge-to-edge feel
+- **Vary background darkness across slides** — alternate between dark, medium, and light backgrounds to create visual rhythm
+
+### Slide Layout Rhythm
+
+When to use each of the 8 layout variants:
+
+| Type | When to Use |
+|---|---|
+| **Title** | Bold title with accent word, subtitle, optional badge — always first |
+| **Stats** | Early for credibility; 2–4 stat cards with big numbers |
+| **Bullets / Content** | Core message; 3–5 bullets max, or 2–3 sentence body |
+| **Quote** | Emotional punctuation; center-aligned, breaks visual pattern |
+| **Comparison** | Two-column before/after, entity comparison, or pros/cons |
+| **Timeline** | Chronological progression; milestones, history, roadmap, or process steps using `.v-timeline-entry` entries |
+| **Visual / Immersive** | Gradient background with glass overlay, minimal text |
+| **Closing / CTA** | Bold title, short takeaway, optional stat reinforcement |
+
+**Layout rhythm rules:**
+
+- **NEVER** two slides of the same type back-to-back
+- **5–8 slides:** title → stats → bullets → quote → comparison or timeline or visual → closing
+- **3–4 slides:** title → stats or bullets → closing
+- **10+ slides:** repeat content/stats but always separate with a quote, timeline, or visual slide
+- **Every deck needs at least 3 different layout types** — variety creates visual interest
+
+### Slide Anti-Slop Rules
+
+- **NEVER** more than 6 bullet points per slide — if you have more, split into two slides
+- **NEVER** body text smaller than 15px — cut words instead of shrinking
+- **NEVER** the same background color on consecutive slides — vary dark/light/gradient
+- **NEVER** skip accent-word on title/heading slides — it's the #1 visual technique
+- **NEVER** use `.v-slide-label` on every single slide — aim for 40–60% of slides
+- **NEVER** center-align bullet slides — only center quotes and closing slides
+- **NEVER** use the same stat value format everywhere — mix `$2.4M`, `147%`, `3x`, `12k+` for variety
+- **NEVER** hand-code charts on slides — use `vellum.widgets.lineChart()` / `.barChart()` / `.sparkline()` / `.progressRing()` rendered into a `<div>` with a fixed height. Hand-coded chart SVGs bleed into adjacent slide elements.
+
+### Slide Pre-Ship Checklist
+
+Before delivering any slide deck, verify:
+
+1. **Domain-matched palette** — colors match the topic (not default violet for everything)
+2. **Bold background** — dark, gradient, or strongly tinted; not plain white
+3. **Accent word in every title** — one key word colored with the accent
+4. **One idea per slide** — each slide understood in 3 seconds
+5. **Layout variety** — 3+ different layout types, no consecutive same-type
+6. **Typography scale** — clear hierarchy; titles much larger than body text
+7. **Sparse content** — max 6 bullets, max 3 sentences body text per slide
+8. **Visual punctuation** — at least one quote, visual, or center-aligned slide
+9. **Strong open and close** — impactful title slide, clear takeaway closing
+10. **Immersive feel** — full-viewport slides, `min-height: 100vh; border-radius: 0`
+
+### What Great Slide Decks Look Like
+
+- **Startup pitch deck** — dark navy animated gradient, accent-word title, trust pill on stats, big stat numbers (`$12M ARR`, `3x growth`), customer quote mid-deck, CTA closing with one bold ask
+- **Company overview** — corporate blue on charcoal, stats-heavy early slides, comparison slide (us vs. competitors), timeline slide, professional/minimal emoji usage
+- **Educational deck** — bright accent on light background, emoji in bullet points for visual anchoring, expert quote, glass overlay visual slide, "key takeaways" closing
+- **Creative agency deck** — bold saturated palette, animated gradient backgrounds, minimal text per slide, maximum visual drama, notable client quote, portfolio-style comparison
 
 ## Error Handling
 

package/src/config/bundled-skills/app-builder/TOOLS.json

@@ -50,7 +50,7 @@
               "title": { "type": "string", "description": "Preview card title" },
               "subtitle": { "type": "string", "description": "Optional subtitle" },
               "description": { "type": "string", "description": "Optional short description" },
-              "icon": { "type": "string", "description": "Optional emoji icon" },
+              "icon": { "type": "string", "description": "Optional icon — image URL preferred when available (logo, favicon, photo, etc.), emoji as fallback" },
               "metrics": {
                 "type": "array",
                 "description": "Optional key-value metrics",

package/src/config/bundled-skills/email-setup/SKILL.md

@@ -9,7 +9,7 @@ You are setting up your own personal email address. This is a one-time operation
 
 ## Prerequisites
 
-Only proceed if the user explicitly asks you to create or set up your email address. Do NOT proactively run this skill.
+Only proceed if the user explicitly asks you to create or set up **your own** (the assistant's) email address — e.g., "set up your email", "create your email address", "I want you to have your own email". Generic email requests like "send an email", "check my email", or "set up email" are about the **user's Gmail** and should be handled by the Messaging skill, not this one. Do NOT proactively run this skill.
 
 ## Step 1: Check if Email Already Exists
 

package/src/config/bundled-skills/google-oauth-setup/SKILL.md

@@ -193,36 +193,36 @@ After the user authorizes (they'll come back and say so, or you can suggest they
 
 # Path B: Automated Setup (macOS Desktop App)
 
-You will automate the entire GCP setup via the browser while the user watches via screencast. The user's only manual actions are signing in to their Google account and one copy-paste for the client secret.
+You will automate the entire GCP setup via the browser while the user watches in the Chrome window on the side. The user's only manual actions are: signing in to their Google account, and copy-pasting credentials from the Chrome window into secure prompts.
 
 ## Browser Interaction Principles
 
 Google Cloud Console's UI changes frequently. Do NOT memorize or depend on specific element IDs, CSS selectors, or DOM structures. Instead:
 
-1. **Screenshot first, act second.** Before every interaction, take a `browser_screenshot` to see the current visual state. Use `browser_snapshot` to find interactive elements.
-2. **Adapt to what you see.** If a button's label or position differs from what you expect, use the screenshot to find the correct element. GCP may rename buttons, reorganize menus, or change form layouts at any time.
-3. **Verify after every action.** After clicking, typing, or navigating, take a new screenshot to confirm the action succeeded. If it didn't, try an alternative interaction (e.g., if a dropdown didn't open on click, try pressing Space or Enter).
-4. **Never assume DOM structure.** Dropdowns may be `<select>`, `<mat-select>`, `<div role="listbox">`, or something else entirely. Use the snapshot to identify what's on the page and interact accordingly.
-5. **When stuck, screenshot and describe.** If you cannot find an expected element after 2 attempts, take a screenshot, describe what you see to the user, and ask for guidance.
+1. **Snapshot first, act second.** Before every interaction, use `browser_snapshot` to discover interactive elements and their IDs. This is your primary navigation tool — it gives you the accessibility tree with clickable/typeable element IDs. Use `browser_screenshot` for visual context when the snapshot alone isn't enough.
+2. **Adapt to what you see.** If an element's label or position differs from what you expect, use the snapshot to find the correct element. GCP may rename buttons, reorganize menus, or change form layouts at any time.
+3. **Verify after every action.** After clicking, typing, or navigating, take a new snapshot to confirm the action succeeded. If it didn't, try an alternative interaction (e.g., if a dropdown didn't open on click, try pressing Space or Enter on the element).
+4. **Never assume DOM structure.** Dropdowns may be `<select>`, `<mat-select>`, `<div role="listbox">`, or something else entirely. Use the snapshot to identify element types and interact accordingly.
+5. **When stuck after 2 attempts, describe and ask.** Take a screenshot, describe what you see to the user, and ask for guidance.
 
 ## Anti-Loop Guardrails
 
 Each step has a **retry budget of 3 attempts**. An attempt is one try at the step's primary action (e.g., clicking a button, filling a form). If a step fails after 3 attempts:
 
 1. **Stop trying.** Do not continue retrying the same approach.
-2. **Fall back to manual.** Tell the user what you were trying to do and ask them to complete that step manually in the browser. Give them the direct URL and clear text instructions.
+2. **Fall back to manual.** Tell the user what you were trying to do and ask them to complete that step manually in the Chrome window (which they can see on the side). Give them the direct URL and clear text instructions.
 3. **Resume automation** at the next step once the user confirms the manual step is done.
 
-If **two or more steps** require manual fallback, abandon the automated flow entirely and switch to giving the user the remaining steps as clear text instructions with links — using the correct OAuth type for the current flow (Desktop app for macOS, Web application for channels).
+If **two or more steps** require manual fallback, abandon the automated flow entirely and switch to giving the user the remaining steps as clear text instructions with links — using "Desktop app" as the OAuth application type.
 
 ## Things That Do Not Work — Do Not Attempt
 
 These actions are technically impossible in the browser automation environment. Attempting them wastes time and leads to loops:
 
-- **Downloading files.** `browser_click` on a Download button does not save files to disk. The downloaded file will not appear anywhere accessible. There is NO JSON file to find at `~/Downloads` or anywhere else.
-- **Reading the Client Secret from a screenshot.** The Client Secret IS visible in the creation dialog, but you MUST NOT attempt to read it from a screenshot — it is too easy to misread characters, and the value must be exact. Always use the `credential_store prompt` approach to let the user copy-paste it accurately.
-- **Clipboard operations.** You cannot copy/paste via browser automation.
+- **Downloading files.** `browser_click` on a Download button does not save files to disk. There is NO JSON file to find at `~/Downloads` or anywhere else. Never click Download buttons.
+- **Clipboard operations.** You cannot copy/paste via browser automation. The user must manually copy values from the Chrome window.
 - **Deleting and recreating OAuth clients** to get a fresh secret — this orphans the stored client_id and causes `invalid_client` errors.
+- **Navigating away from the credential dialog** before both credentials are stored — you will lose the Client Secret display and cannot get it back without creating a new client.
 
 ## Step 1: Single Upfront Confirmation
 
@@ -231,10 +231,11 @@ Use `ui_show` with `surface_type: "confirmation"` and this message:
 > **Set up Google Cloud for Gmail & Calendar**
 >
 > Here's what will happen:
-> 1. **A browser opens** — you sign in to your Google account
-> 2. **I automate everything** — project creation, APIs, OAuth config, credentials
-> 3. **One quick copy-paste** — I'll create OAuth credentials and ask you to copy-paste the Client Secret from the dialog into a secure prompt
-> 4. **You authorize Vellum** with one click
+> 1. **A browser opens on the side** — you'll be able to watch everything I do
+> 2. **You sign in** to your Google account in the browser
+> 3. **I automate everything** — project creation, APIs, OAuth config, credentials
+> 4. **One copy-paste** — I'll ask you to copy the Client Secret from the browser into a secure prompt
+> 5. **You authorize Vellum** with one click
 >
 > The whole thing takes 2-3 minutes. Ready?
 
@@ -246,24 +247,32 @@ If the user declines, acknowledge and stop. No further confirmations are needed
 
 Navigate to `https://console.cloud.google.com/`.
 
-Take a screenshot and snapshot to check the page state:
-- **Sign-in page:** Tell the user: "Please sign in to your Google account in the browser preview panel (or the Chrome window that just opened)." Then auto-detect sign-in completion by polling screenshots every 5-10 seconds. Check if the current URL has moved away from `accounts.google.com` to `console.cloud.google.com`. Do NOT ask the user to "let me know when you're done" — detect it automatically. Once sign-in is detected, tell the user: "Signed in! Starting the automated setup now..."
+Take a screenshot to check the page state:
+
+- **Sign-in page:** Tell the user: "Please sign in to your Google account in the Chrome window on the right side of your screen." Then auto-detect sign-in completion by polling with `browser_screenshot` every 5-10 seconds — check if the URL has moved away from `accounts.google.com` to `console.cloud.google.com`. Do NOT ask the user to "let me know when you're done" — detect it automatically. Once sign-in is detected, tell the user: "Signed in! Starting the automated setup now..."
 - **Already signed in:** Tell the user: "Already signed in — starting setup now..." and continue immediately.
 - **CAPTCHA:** The browser automation's built-in handoff will handle this. If it persists, tell the user: "There's a CAPTCHA in the browser — please complete it and I'll continue automatically."
 
-**Verify:** URL contains `console.cloud.google.com` and no sign-in overlay is visible.
+**What you should see when done:** URL contains `console.cloud.google.com` and no sign-in overlay is visible.
 
 ## Step 3: Create or Select a Project
 
 **Goal:** A GCP project named "Vellum Assistant" exists and is selected.
 
-Tell the user: "Creating Google Cloud project 'Vellum Assistant'..."
+Tell the user: "Creating Google Cloud project..."
+
+Navigate to `https://console.cloud.google.com/projectcreate`.
+
+Take a `browser_snapshot`. Find the project name input field (look for an element with label containing "Project name" or a text input near the top of the form). Type "Vellum Assistant" into it.
 
-Navigate to `https://console.cloud.google.com/projectcreate`. Take a screenshot. Find the project name input field, enter "Vellum Assistant", and submit the form.
+Look for a "Create" button in the snapshot and click it. Wait 10-15 seconds for project creation — take a screenshot to check for:
+- **Success message** or redirect to the new project dashboard — note the project ID from the URL or page content.
+- **"Project name already in use" error** — that's fine. Navigate to `https://console.cloud.google.com/cloud-resource-manager` to find and select the existing "Vellum Assistant" project. Use `browser_extract` to read the project ID from the page.
+- **Organization restriction or quota error** — tell the user what happened and ask them to resolve it.
 
-If the project already exists (e.g., an error says the name is taken or you see it in the project list), select the existing project instead. Note the project ID for subsequent steps.
+**What you should see when done:** The project selector in the top bar shows the project name, and you have the project ID (something like `vellum-assistant-12345`).
 
-**Verify:** Take a screenshot. The console shows the project is active (project name visible in the header bar or a success message). Record the project ID.
+Tell the user: "Project created!"
 
 ## Step 4: Enable Gmail and Calendar APIs
 
@@ -275,98 +284,111 @@ Navigate to each API's library page and enable it if not already enabled:
 1. `https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=PROJECT_ID`
 2. `https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=PROJECT_ID`
 
-For each page: take a screenshot. If the API shows as already enabled (e.g., "Manage" button or "API enabled" status), skip it. Otherwise, find and click the enable button, then wait for confirmation.
+For each page: take a `browser_snapshot`. Look for:
+- **"Enable" button** — click it, wait a few seconds, take another snapshot to confirm.
+- **"Manage" button or "API enabled" text** — the API is already enabled. Skip it.
 
-**Verify:** Both API pages show an enabled/active state.
+**What you should see when done:** Both API pages show "Manage" or "API enabled" status.
+
+Tell the user: "APIs enabled!"
 
 ## Step 5: Configure OAuth Consent Screen
 
 **Goal:** An OAuth consent screen is configured with External user type, the required scopes, and the user added as a test user.
 
-Tell the user: "Configuring OAuth consent screen — this is the longest step, but it's fully automated..."
+Tell the user: "Setting up OAuth consent screen — this is the longest step but it's fully automated..."
 
 Navigate to `https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID`.
 
-Take a screenshot. If the consent screen is already configured (you see a dashboard with app info), skip to Step 6.
+Take a `browser_snapshot` and `browser_screenshot`. Check the page state:
 
-Otherwise, work through the consent screen wizard. The wizard has multiple pages — progress through each:
+### If the consent screen is already configured
 
-**App information page:**
-- Select "External" user type if prompted
-- App name: "Vellum Assistant"
-- User support email: select the user's email (this may be a dropdown or text input — adapt to what you see)
-- Developer contact email: enter the user's email
-- Submit / Save and Continue
+You'll see a dashboard showing the app name ("Vellum Assistant" or similar) with an "Edit App" button. **Skip to Step 6.**
 
-**Scopes page:**
-- Add these scopes:
-  - `https://www.googleapis.com/auth/gmail.readonly`
-  - `https://www.googleapis.com/auth/gmail.modify`
-  - `https://www.googleapis.com/auth/gmail.send`
-  - `https://www.googleapis.com/auth/calendar.readonly`
-  - `https://www.googleapis.com/auth/calendar.events`
-  - `https://www.googleapis.com/auth/userinfo.email`
-- Save and Continue
+### If you see a user type selection (External / Internal)
 
-**Test users page:**
-- Add the user's email as a test user
-- Save and Continue
+Select **"External"** and click **Create** or **Get Started**.
 
-**Summary page:**
-- Return to dashboard
+### Consent screen form (wizard or single-page)
 
-**Verify:** The consent screen dashboard shows "Vellum Assistant" with the configured scopes.
+Google Cloud uses either a multi-page wizard or a single-page form. Adapt to what you see:
 
-## Step 6: Create OAuth Credentials and Capture Both Client ID and Secret
+**App information section:**
+- **App name**: Type "Vellum Assistant" in the app name field.
+- **User support email**: This is typically a dropdown showing the signed-in user's email. Use `browser_snapshot` to find a `<select>` or clickable dropdown element near "User support email". Select the user's email.
+- **Developer contact email**: Type the user's email into this field. (Use the same email visible in the support email dropdown if you can read it, or use `browser_extract` to find the email shown on the page.)
+- Click **Save and Continue** if on a multi-page wizard.
 
-**Goal:** A "Desktop app" OAuth client exists, and both its Client ID and Client Secret are stored in the vault.
+**Scopes section:**
+- Click **"Add or Remove Scopes"** (or similar button).
+- In the scope picker dialog, look for a text input labeled **"Manually add scopes"** or **"Filter"** at the bottom or top of the dialog.
+- Paste all 6 scopes at once as a comma-separated string into that input:
+  ```
+  https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.send,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/calendar.events,https://www.googleapis.com/auth/userinfo.email
+  ```
+- Click **"Add to Table"** or **"Update"** to confirm the scopes.
+- If no manual input is available, you'll need to search for and check each scope individually using the scope tree. Search for each scope URL in the filter box and check its checkbox.
+- Click **Save and Continue** (or **Update** then **Save and Continue**).
 
-### CRITICAL — Credential Capture Protocol
+**Test users section:**
+- Click **"Add Users"** or similar.
+- Enter the user's email address.
+- Click **Add** then **Save and Continue**.
 
-When you create the OAuth client, Google shows a **single dialog** with the Client ID, Client Secret, and a Download button. You MUST follow this exact sequence — **no improvisation**:
+**Summary section:**
+- Click **"Back to Dashboard"** or **"Submit"**.
 
-1. Read the **Client ID** from the screen (it is visible and safe to read).
-2. Store the Client ID via `credential_store store`.
-3. **IMMEDIATELY** present a `credential_store prompt` for the Client Secret. This is your ONLY next action after storing the Client ID. Do not attempt anything else.
-4. Wait for the user to paste the secret.
+**What you should see when done:** A consent screen dashboard showing "Vellum Assistant" as the app name.
 
-**Absolute prohibitions during this step:**
-- Do NOT click the Download button. There is no JSON file. Downloads do not work.
-- Do NOT try to read the Client Secret from the screenshot. It is visible on screen but must come from the user via secure prompt to ensure accuracy.
-- Do NOT navigate away from the dialog, close it, or interact with any other element until the user has pasted the secret.
-- Do NOT mention JSON files, downloads, or `~/Downloads` to the user — none of these exist.
+Tell the user: "Consent screen configured!"
 
-### 6a: Create the credential
+## Step 6: Create OAuth Credentials and Capture Them
+
+**Goal:** A "Desktop app" OAuth client exists, and both its Client ID and Client Secret are stored in the vault.
 
 Tell the user: "Creating OAuth credentials..."
 
+### 6a: Create the credential
+
 Navigate to `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`.
 
-Find the option to create new credentials (typically a button labeled "Create Credentials" or similar), then select "OAuth client ID" from the menu.
+Take a `browser_snapshot`. Find and click a button labeled **"Create Credentials"** or **"+ Create Credentials"**. A dropdown menu should appear — take another snapshot and click **"OAuth client ID"**.
 
-On the creation form:
-- Application type: **Desktop app**
-- Name: "Vellum Assistant"
-- Do NOT add any redirect URIs for the desktop app flow
+On the creation form (take a snapshot to see the fields):
+- **Application type**: Find the dropdown and select **"Desktop app"**. This may be a `<select>` element or a custom dropdown — use the snapshot to identify it. You might need to click the dropdown first, then take another snapshot to see the options, then click "Desktop app".
+- **Name**: Type "Vellum Assistant" in the name field.
+- Do NOT add any redirect URIs — the desktop app flow doesn't need them.
 
-Submit the form.
+Click **"Create"** to submit the form.
 
-### 6b: Read Client ID and IMMEDIATELY prompt for Client Secret
+### 6b: Capture credentials from the dialog
 
-After creation, a dialog will display the new Client ID and Client Secret. Handle **both** in this single step:
+After creation, a dialog will display the **Client ID** and **Client Secret**. This is the critical step.
 
-**First**, read the **Client ID** from the screen. It looks like `123456789-xxxxx.apps.googleusercontent.com`. Store it:
+**First**, try to auto-read the **Client ID** using `browser_extract`. The Client ID matches the pattern `*.apps.googleusercontent.com`. Search the extracted text for this pattern. If found, store it:
 
 ```
 credential_store store:
   service: "integration:gmail"
   field: "client_id"
-  value: "<the Client ID you read from the screen>"
+  value: "<the Client ID extracted from the page>"
 ```
 
-**Then IMMEDIATELY** — with no other actions in between — tell the user:
+If `browser_extract` fails to find the Client ID, prompt the user instead:
 
-> "Got the Client ID! Now I need the Client Secret. In the dialog still open in the browser, you'll see the **Client Secret** value (starts with `GOCSPX-`). Please copy it and paste it into the secure prompt below."
+```
+credential_store prompt:
+  service: "integration:gmail"
+  field: "client_id"
+  label: "Google OAuth Client ID"
+  description: "Copy the Client ID from the dialog in the Chrome window and paste it here. It looks like 123456789-xxxxx.apps.googleusercontent.com"
+  placeholder: "xxxxx.apps.googleusercontent.com"
+```
+
+**Then** — whether the Client ID was auto-read or prompted — tell the user:
+
+> "Got the Client ID! Now I need the Client Secret. You can see it in the dialog in the Chrome window — it starts with `GOCSPX-`. Please copy it and paste it into the secure prompt below."
 
 And present the secure prompt:
 
@@ -379,17 +401,19 @@ credential_store prompt:
   placeholder: "GOCSPX-..."
 ```
 
-Wait for the user to complete the prompt. Do not take any other action until they do.
+Wait for the user to complete the prompt. **Do not take any other browser actions until the user has pasted the secret.** The dialog must stay open so they can see and copy the value.
 
-If the user has trouble locating the secret, take a `browser_screenshot` and help them find it on the page — but do NOT attempt to read the secret value yourself.
+If the user has trouble locating the secret, take a `browser_screenshot` and describe where the secret field is on the screen — but do NOT attempt to read the secret value yourself. It must come from the user for accuracy.
 
-**Verify:** `credential_store list` shows both `client_id` and `client_secret` for `integration:gmail`.
+**What you should see when done:** `credential_store list` shows both `client_id` and `client_secret` for `integration:gmail`.
+
+Tell the user: "Credentials stored securely!"
 
 ## Step 7: OAuth2 Authorization
 
 **Goal:** The user authorizes Vellum to access their Gmail and Calendar via OAuth.
 
-Tell the user: "Opening Google sign-in so you can authorize Vellum. Just click 'Allow' on the consent page."
+Tell the user: "Opening Google authorization — just click 'Allow' on the consent page."
 
 Use `credential_store` with:
 
@@ -400,19 +424,19 @@ service: "integration:gmail"
 
 This auto-reads client_id and client_secret from the secure store and auto-fills auth_url, token_url, scopes, and extra_params from well-known config.
 
-**If the user sees a "This app isn't verified" warning:** Tell them this is normal for apps in testing mode. Click "Advanced" then "Go to Vellum Assistant (unsafe)" to proceed.
+**If the user sees a "This app isn't verified" warning:** Tell them: "You'll see an 'app isn't verified' warning — this is normal for personal apps in testing mode. Click **Advanced**, then **Go to Vellum Assistant (unsafe)** to proceed."
 
 **Verify:** The `oauth2_connect` call returns a success message with the connected account email.
 
 ## Step 8: Done!
 
-"**Gmail and Calendar are connected!** You can now read, search, and send emails, plus view and manage your calendar. Try asking me to check your inbox or show your upcoming events!"
+Tell the user: "**Gmail and Calendar are connected!** You can now read, search, and send emails, plus view and manage your calendar. Try asking me to check your inbox or show your upcoming events!"
 
 ## Error Handling
 
 - **Page load failures:** Retry navigation once. If it still fails, tell the user and ask them to check their internet connection.
 - **Permission errors in GCP:** The user may need billing enabled or organization-level permissions. Explain clearly and ask them to resolve it.
 - **Consent screen already configured:** Don't overwrite — skip to credential creation.
-- **Element not found:** Take a fresh screenshot to re-assess. The GCP UI may have changed. Describe what you see and try alternative approaches. If stuck after 2 attempts, ask the user for guidance.
+- **Element not found:** Take a fresh `browser_snapshot` to re-assess. The GCP UI may have changed. Describe what you see and try alternative approaches. If stuck after 2 attempts, ask the user for guidance — they can see the Chrome window too.
 - **OAuth flow timeout or failure:** Offer to retry. The credentials are already stored, so reconnecting only requires re-running the authorization flow.
 - **Any unexpected state:** Take a `browser_screenshot`, describe what you see, and ask the user for guidance.