@vellumai/assistant 0.3.0

package/src/config/vellum-skills/deploy-fullstack-vercel/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: "Deploy Fullstack to Vercel"
+description: "Build and deploy a full-stack app (React frontend + Python/FastAPI backend) to Vercel as a serverless demo with seeded data"
+metadata: {"vellum": {"emoji": "🚀"}}
+
+---
+
+# Deploy Fullstack to Vercel
+
+Deploy a full-stack app with a React/Vite frontend and Python/FastAPI backend to Vercel as a serverless demo. No auth required — meant for demos, portfolio pieces, and quick showcases.
+
+## When to Use
+
+- User says "deploy this to Vercel", "host this", "publish this"
+- User has a project with a frontend + backend they want live
+- User wants a quick demo deployment (no persistent database needed)
+
+## Prerequisites
+
+- A project with a frontend (React/Vite) and backend (FastAPI/Python)
+- Vercel CLI installed (`npm install -g vercel`) and authenticated (`vercel login`)
+
+## Workflow
+
+### 1. Build the Frontend
+
+```bash
+cd <project>/frontend
+npm install
+npx vite build
+```
+
+This produces static files in `frontend/dist/`.
+
+### 2. Create the Vercel Deploy Directory
+
+```
+<project>/vercel-deploy/
+├── api/
+│   ├── index.py          ← FastAPI app wrapper (entry point)
+│   ├── database.py        ← DB config (use /tmp for SQLite)
+│   ├── models.py
+│   ├── schemas.py
+│   ├── seed_data.py       ← Must seed ALL required data (users, etc.)
+│   ├── routers/
+│   │   ├── __init__.py
+│   │   └── *.py
+│   └── requirements.txt   ← Python deps (fastapi, sqlalchemy, pydantic)
+├── index.html             ← From frontend/dist/
+├── assets/                ← From frontend/dist/assets/
+└── vercel.json
+```
+
+**Key steps:**
+```bash
+mkdir -p <project>/vercel-deploy/api
+
+# Copy frontend build output to deploy root
+cp -r <project>/frontend/dist/* <project>/vercel-deploy/
+
+# Copy backend files into api/
+cp <project>/backend/models.py <project>/vercel-deploy/api/
+cp <project>/backend/database.py <project>/vercel-deploy/api/
+cp <project>/backend/schemas.py <project>/vercel-deploy/api/
+cp <project>/backend/seed_data.py <project>/vercel-deploy/api/
+cp -r <project>/backend/routers <project>/vercel-deploy/api/
+cp <project>/backend/requirements.txt <project>/vercel-deploy/api/
+```
+
+### 3. Create api/index.py (Serverless Entry Point)
+
+```python
+import sys, os
+sys.path.insert(0, os.path.dirname(__file__))
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from database import engine, Base, SessionLocal
+from seed_data import seed_exercises, seed_default_user  # all seed functions
+from routers import users, exercises, workouts, schedule, progress
+
+# Create tables and seed on EVERY cold start
+Base.metadata.create_all(bind=engine)
+db = SessionLocal()
+try:
+    seed_exercises(db)
+    seed_default_user(db)  # IMPORTANT: seed all required data
+finally:
+    db.close()
+
+app = FastAPI(title="MyApp")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(users.router)
+# ... other routers
+
+@app.get("/api/health")
+def health_check():
+    return {"status": "ok"}
+```
+
+### 4. Update database.py for Vercel
+
+**Critical:** Vercel serverless functions can only write to `/tmp`. Update the SQLite path:
+
+```python
+SQLALCHEMY_DATABASE_URL = "sqlite:////tmp/app.db"
+```
+
+### 5. Seed ALL Required Data
+
+**This is the #1 gotcha.** Since `/tmp` is ephemeral, every cold start gets a fresh database. If your frontend assumes certain data exists (like user ID 1), you MUST seed it:
+
+```python
+def seed_default_user(db: Session):
+    count = db.query(UserProfile).count()
+    if count > 0:
+        return
+    user = UserProfile(name="Demo User", ...)
+    db.add(user)
+    db.commit()
+```
+
+### 6. Create vercel.json
+
+```json
+{
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/index.py" },
+    { "source": "/((?!assets/).*)", "destination": "/index.html" }
+  ]
+}
+```
+
+This routes:
+- `/api/*` → Python serverless function
+- Everything else → React SPA (index.html)
+
+### 7. Deploy
+
+```bash
+cd <project>/vercel-deploy
+vercel --yes --prod
+```
+
+### 8. Verify
+
+```bash
+curl -s <deployed-url>/api/health
+# Should return: {"status":"ok"}
+```
+
+## Gotchas & Limitations
+
+| Issue | Solution |
+|-------|----------|
+| SQLite resets on cold start | Seed ALL required data in index.py startup |
+| No persistent storage | Acceptable for demos. For production, use Vercel Postgres or Supabase |
+| No auth | Fine for demos/portfolios. Add auth layer for real apps |
+| `requirements.txt` location | Must be inside `api/` folder (next to index.py) |
+| Module imports in routers | Use `sys.path.insert(0, os.path.dirname(__file__))` in index.py |
+| CORS | Set `allow_origins=["*"]` for demo deployments |
+| `--name` flag deprecated | Don't use `--name` with Vercel CLI, just deploy from the directory |
+
+## Vercel CLI Quick Reference
+
+```bash
+npm install -g vercel    # Install
+vercel login             # Authenticate (opens browser)
+vercel --yes --prod      # Deploy to production (skip prompts)
+vercel logs --project <name>  # Check function logs
+```

package/src/config/vellum-skills/document-writer/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: "Document Writer"
+description: "Create and edit long-form documents like blog posts, articles, essays, and reports using the built-in rich text editor"
+user-invocable: true
+metadata: {"vellum": {"emoji": "📝"}}
+---
+
+You are helping your user write long-form content (blog posts, articles, essays, reports, documentation) using the built-in document editor. This skill should be used whenever the user asks to write, draft, or create any document-like content.
+
+## When to Use This Skill
+
+**ALWAYS use this skill when the user asks for:**
+- Blog posts
+- Articles
+- Essays
+- Reports
+- Guides or tutorials
+- Documentation
+- Any long-form written content (500+ words)
+
+**DO NOT use this skill for:**
+- Short responses or explanations (< 500 words)
+- Code snippets or technical implementations
+- Interactive apps or dashboards (use `app_create` instead)
+- Quick summaries
+
+## Workflow
+
+### Step 1: Create the Document
+
+Use `document_create` to open the built-in rich text editor:
+
+```json
+{
+  "title": "The title of the document (inferred from user's request)",
+  "initial_content": "Optional starting content in Markdown format"
+}
+```
+
+**Important:** The editor opens in the Documents tab of the Directory panel, with chat docked to the side. The user can see both the editor and chat simultaneously.
+
+### Step 2: Generate Content
+
+Write the content in **Markdown format**. Use proper structure:
+
+- `#` for main title
+- `##` for section headings
+- `###` for subsections
+- `**bold**` and `*italic*` for emphasis
+- ` ```language ` for code blocks
+- `[text](url)` for links
+- `- ` or `1. ` for lists
+- `> ` for blockquotes
+- Tables, images, and other Markdown features as appropriate
+
+**Quality standards:**
+- Write in clear, engaging prose appropriate for the content type
+- Use active voice and vary sentence structure
+- Break content into logical sections with descriptive headings
+- Include transitions between sections
+- For technical content: use code blocks with syntax highlighting
+- For data-heavy content: use Markdown tables
+
+### Step 3: Stream Content to Editor
+
+Use `document_update` to send content to the editor as you generate it:
+
+```json
+{
+  "surface_id": "doc-xyz",
+  "content": "# Main Title\n\nYour content here...",
+  "mode": "append"
+}
+```
+
+**Streaming strategy:**
+- Generate content in logical chunks (paragraphs or sections)
+- Use `mode: "append"` to stream chunks as you write
+- The content appears in real-time in the editor
+- Don't wait to generate everything before sending - stream it!
+
+### Step 4: Handle User Edits and Requests
+
+The user can request changes via the docked chat while viewing the document:
+
+**Common requests:**
+- "Make the intro shorter"
+- "Add a section about X"
+- "Change the tone to be more formal"
+- "Fix the grammar in paragraph 3"
+
+**How to respond:**
+- Acknowledge the request
+- Generate the updated content
+- Use `document_update` with:
+  - `mode: "replace"` for complete rewrites
+  - `mode: "append"` for additions at the end
+  - For edits in the middle: use `mode: "replace"` with the full updated document
+
+### Step 5: Finalize
+
+Once the user is satisfied:
+- Confirm the document is complete
+- Remind them that it's automatically saved in the Generated panel
+- Let them know they can continue editing manually or ask for more changes
+
+## Examples
+
+### Example 1: Blog Post Request
+
+**User:** "Write a blog post about the future of AI"
+
+**Your response:**
+```
+I'll create a document for your blog post about the future of AI.
+```
+
+Then:
+1. Call `document_create` with `title: "The Future of AI"`
+2. Generate content in chunks, calling `document_update` repeatedly:
+   - First chunk: `# The Future of AI\n\nArtificial intelligence is...`
+   - Second chunk: `## Current State\n\nToday, AI systems...`
+   - Third chunk: `## Emerging Trends\n\n1. **Multimodal AI**...`
+   - Continue until complete
+
+### Example 2: Edit Request
+
+**User (after initial creation):** "Add a section about ethical considerations"
+
+**Your response:**
+```
+I'll add a section on AI ethics.
+```
+
+Then:
+1. Call `document_update` with `mode: "append"` and content:
+   ```markdown
+   ## Ethical Considerations
+
+   As AI systems become more powerful, we must address...
+   ```
+
+### Example 3: Full Rewrite
+
+**User:** "Rewrite this in a more casual tone"
+
+**Your response:**
+```
+I'll rewrite the article in a more casual, conversational tone.
+```
+
+Then:
+1. Call `document_update` with `mode: "replace"` and the complete rewritten content
+
+## Important Notes
+
+- **Documents are automatically saved** and accessible via the Generated panel
+- The user can **manually edit documents** at any time - your role is to assist with generation and refinement
+- The editor supports **drag-and-drop images**, which are converted to base64 inline
+- **Word count is tracked** automatically and displayed to the user
+- **Toast UI Editor** is used, which provides both Markdown and WYSIWYG editing modes
+- Always **acknowledge the document creation** before calling `document_create`
+
+## Error Handling
+
+- If `document_create` fails, the user may not have the client connected. Ask them to check their connection.
+- If the user asks to edit a specific part but you don't have the full document context, ask them to clarify which section or provide more context.
+- If you're unsure about the content direction, ask clarifying questions before generating.
+
+## Anti-Patterns (DO NOT DO THIS)
+
+❌ **Don't use `app_create` for blog posts or articles**
+- Blog posts should use `document_create`, not `app_create`
+- Apps are for interactive content with state/data
+
+❌ **Don't write everything at once without streaming**
+- Use `document_update` with `mode: "append"` to stream chunks
+- Users want to see content appear in real-time
+
+❌ **Don't ask for explicit approval before creating the document**
+- If the user asks for a blog post, create it immediately
+- They can always request changes after
+
+❌ **Don't output the full content in chat**
+- The content goes in the document editor, not in the chat response
+- Just acknowledge what you're doing and stream to the editor
+
+## Success Criteria
+
+✅ Document editor opens in the Documents tab
+✅ Content appears in real-time as you generate it
+✅ User can see both the editor and chat side-by-side
+✅ Content is well-structured with proper Markdown formatting
+✅ User can request edits via chat and you respond appropriately
+✅ Final document is saved and accessible in Generated panel

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

@@ -0,0 +1,199 @@
+---
+name: "Google OAuth Setup"
+description: "Create Google Cloud OAuth credentials for Gmail integration using browser automation"
+user-invocable: true
+includes: ["browser", "public-ingress"]
+metadata: {"vellum": {"emoji": "\ud83d\udd11"}}
+---
+
+You are helping your user create Google Cloud OAuth credentials so the Gmail and Google Calendar integrations can connect. Walk through each step below using `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_click`, `browser_type`, and `browser_extract` tools.
+
+**Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
+
+## Prerequisites
+
+Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+
+## Before You Start
+
+Tell the user:
+- "I'll walk you through setting up Google Cloud so Vellum can connect to your Gmail and Google Calendar. The whole process takes a few minutes."
+- "I'll be automating the Google Cloud Console in the browser — you'll be able to see everything I'm doing."
+- "I'll ask for your approval before each major step, so nothing happens without your say-so."
+- "No sensitive credentials will be shown in the conversation."
+
+## Step 1: Navigate to Google Cloud Console
+
+Tell the user: "First, let me open Google Cloud Console."
+
+Use `browser_navigate` to go to `https://console.cloud.google.com/`.
+
+Take a `browser_screenshot` to show the user what loaded, then take a `browser_snapshot` to check the page state:
+- **If a sign-in page appears:** Tell the user "Please sign in to your Google account in the browser window. Let me know when you're done." Wait for their confirmation, then take another snapshot.
+- **If a CAPTCHA appears:** Tell the user "There's a CAPTCHA to solve. Please complete it in the browser window and let me know." Wait, then retry.
+- **If the console dashboard loads:** Tell the user "Google Cloud Console is loaded. Let's get started!" and continue to Step 2.
+
+## Step 2: Create or Select a Project
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
+
+> **Create a Google Cloud Project**
+>
+> I'm about to create a new Google Cloud project called "Vellum Assistant". This is completely free and won't affect any of your existing projects. The project is just a container for the Gmail API credentials.
+
+Wait for the user to approve. If they decline, explain that a project is required for OAuth credentials and offer to try again or cancel the setup.
+
+Once approved, navigate to `https://console.cloud.google.com/projectcreate`.
+
+Take a `browser_snapshot`. Fill in the project name form:
+- Use `browser_type` to set the project name to "Vellum Assistant"
+- Use `browser_click` to submit the "Create" button
+
+Wait a few seconds, then take a `browser_screenshot` to show the user what happened, and a `browser_snapshot` to confirm the project was created. If the project already exists, that's fine — navigate to its dashboard.
+
+Tell the user: "Project created! Now let's enable the Gmail API."
+
+Note the project ID from the URL or page content for subsequent steps.
+
+## Step 3: Enable the Gmail and Calendar APIs
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
+
+> **Enable the Gmail and Calendar APIs**
+>
+> I'm about to enable the Gmail API and Google Calendar API in your Google Cloud project. This allows Vellum to access your email and calendar — but only after you explicitly authorize it in a later step. Enabling the APIs alone doesn't grant any access.
+
+Wait for the user to approve. If they decline, explain that the APIs are required for email and calendar integration and offer to try again or cancel.
+
+Once approved, navigate to `https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=PROJECT_ID` (substitute the actual project ID).
+
+Take a `browser_snapshot`:
+- **If the API is already enabled:** You'll see "API enabled" or a "Manage" button. Tell the user "Gmail API is already enabled — great!" and continue to enable Calendar API.
+- **If not enabled:** Use `browser_click` on the "Enable" button.
+
+Wait a moment, then take a `browser_screenshot` to show the result and a `browser_snapshot` to confirm it shows as enabled.
+
+Now navigate to `https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=PROJECT_ID` to enable the Google Calendar API.
+
+Take a `browser_snapshot`:
+- **If the API is already enabled:** Tell the user "Google Calendar API is already enabled — great!" and skip to Step 4.
+- **If not enabled:** Use `browser_click` on the "Enable" button.
+
+Wait a moment, then take a `browser_screenshot` to show the result.
+
+Tell the user: "Gmail and Calendar APIs are enabled! Next, we need to set up an OAuth consent screen."
+
+## Step 4: Configure the OAuth Consent Screen
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
+
+> **Configure OAuth Consent Screen**
+>
+> I'm about to set up an OAuth consent screen for your project. This is the page Google shows when you authorize an app. I'll configure it with your email and the Gmail permissions Vellum needs (read, modify, and send emails). The app will start in "testing" mode — only you will be able to authorize it.
+
+Wait for the user to approve. If they decline, explain that the consent screen is required for the OAuth flow and offer to try again or cancel.
+
+Once approved, navigate to `https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID`.
+
+Take a `browser_snapshot` to check the current state:
+- **If consent screen is already configured:** Tell the user "Consent screen is already set up — skipping ahead!" and go to Step 5.
+- **If a user type selection appears:** Select "External" and click "Create".
+
+Fill in the required fields on the consent screen form:
+1. **App name:** "Vellum Assistant"
+2. **User support email:** Select the user's email from the dropdown
+3. **Developer contact email:** Type the user's email address
+4. Leave other fields as defaults
+
+Use `browser_click` to proceed through each page of the wizard:
+- App information page: Fill fields, click "Save and Continue"
+- Scopes page: Click "Add or Remove Scopes", search for and select:
+  - `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 "Update" then "Save and Continue"
+- Test users page: Add the user's email as a test user, click "Save and Continue"
+- Summary page: Click "Back to Dashboard"
+
+Take a `browser_screenshot` after completing the wizard.
+
+Tell the user: "Consent screen is configured! Almost there — just need to create the credentials."
+
+## Step 5: Create OAuth Credentials
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
+
+> **Create OAuth Credentials**
+>
+> I'm about to create OAuth Web Application credentials for Vellum Assistant. This generates a client ID that Vellum uses to initiate the authorization flow. The redirect URI will point to the gateway's OAuth callback endpoint.
+
+Wait for the user to approve. If they decline, explain that credentials are the final step needed and offer to try again or cancel.
+
+Once approved, navigate to `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`.
+
+Use `browser_click` on "+ Create Credentials" at the top, then select "OAuth client ID" from the dropdown.
+
+Take a `browser_snapshot` and fill in:
+1. **Application type:** Select "Web application" from the dropdown
+2. **Name:** "Vellum Assistant"
+3. **Authorized redirect URIs:** Click "Add URI" and enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable.
+
+Use `browser_click` on the "Create" button.
+
+## Step 6: Extract and Store the Client ID
+
+After creation, a dialog should appear showing the client ID and client secret.
+
+Use `browser_snapshot` or `browser_extract` to read the **Client ID** value from the dialog. The client ID looks like `NUMBERS-CHARS.apps.googleusercontent.com`.
+
+**Important:** You only need the Client ID, not the client secret (PKCE flow is used).
+
+Tell the user: "Credentials created! Now let's connect your Gmail account using the client ID."
+
+## Step 7: Connect Gmail
+
+Tell the user: "Opening Google sign-in so you can authorize Vellum to access your Gmail. You'll see a Google consent page — just click 'Allow'."
+
+Use the `credential_store` tool to connect Gmail via OAuth2:
+
+```
+action: "oauth2_connect"
+service: "integration:gmail"
+client_id: "<the extracted client ID>"
+auth_url: "https://accounts.google.com/o/oauth2/v2/auth"
+token_url: "https://oauth2.googleapis.com/token"
+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"]
+userinfo_url: "https://www.googleapis.com/oauth2/v2/userinfo"
+extra_params: {"access_type": "offline", "prompt": "consent"}
+```
+
+This will open the Google authorization page in the user's browser. Wait for the flow to complete.
+
+**If the user sees a "This app isn't verified" warning:** Tell them this is normal for apps in testing mode. They should click "Advanced" → "Go to Vellum Assistant (unsafe)" to proceed. This warning appears because the app hasn't gone through Google's verification process, which is only needed for apps used by many people.
+
+## Step 8: Celebrate!
+
+Once connected, tell the user:
+
+"**Gmail and Calendar are connected!** You're all set. You can now read, search, and send emails, plus view and manage your calendar through Vellum. Try asking me to check your inbox or show your upcoming events!"
+
+Summarize what was accomplished:
+- Created a Google Cloud project (or used an existing one)
+- Enabled the Gmail API and Google Calendar API
+- Configured the OAuth consent screen with appropriate scopes (including calendar)
+- Created OAuth Web Application credentials with gateway callback redirect URI
+- Connected your Gmail and Google Calendar accounts
+
+## 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 what's needed clearly and ask them to resolve it.
+- **Consent screen already configured with different settings:** Don't overwrite; skip to credential creation and tell the user you're using their existing configuration.
+- **Element not found for click/type:** Take a fresh `browser_snapshot` to re-assess the page layout. GCP UI may have changed; adapt your selectors. Tell the user what you're looking for if you get stuck.
+- **User declines an approval gate:** Don't push back aggressively. Explain briefly why the step matters, offer to try again, or offer to cancel the whole setup gracefully. Never proceed without approval.
+- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry the connect step. The client ID is already stored, so they can also connect later from Settings.
+- **"This app isn't verified" warning:** Guide the user through clicking "Advanced" → "Go to Vellum Assistant (unsafe)". Reassure them this is expected for personal-use OAuth apps.
+- **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask the user for guidance rather than guessing.