@vellumai/assistant 0.3.4 → 0.3.6

package/src/config/bundled-skills/amazon/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: "Amazon"
+description: "Shop on Amazon and Amazon Fresh using the built-in CLI integration"
+user-invocable: true
+metadata: {"vellum": {"emoji": "\uD83D\uDCE6"}}
+---
+
+You can shop on Amazon (and Amazon Fresh for groceries) for the user using the `vellum amazon` CLI.
+
+## CLI Setup
+
+**IMPORTANT: Always use `host_bash` (not `bash`) for all `vellum amazon` commands.** The Amazon CLI needs host access for session cookies and the `vellum` binary — neither of which are available inside the sandbox.
+
+`vellum amazon` is a built-in subcommand of the Vellum assistant CLI — it is NOT a separate tool you need to find or install. It should already be on your PATH. If `vellum` is not found, prepend `PATH="$HOME/.local/bin:$PATH"` to the command. Do NOT search for the binary, inspect wrapper scripts, or try to discover how the CLI works. Just run the commands as documented below.
+
+## Typical Flow — Regular Amazon Shopping
+
+When the user asks you to order something from Amazon:
+
+1. **Check session** — run `vellum amazon status --json`. If `loggedIn` is false or the session is expired, tell the user: "A Chrome window will open to the Amazon login page. Please sign in there — I'll detect your login automatically and minimize the window." Then run `vellum amazon refresh --json`. This starts a Ride Shotgun learn session that records your login and auto-stops once it detects you've signed in. The session is imported automatically. **This command blocks until login is complete — just wait for it.**
+
+2. **Search** — run `vellum amazon search "<query>" --json` to find matching products. Present the top results with ASIN, title, price, and Prime status. If the user named a specific product, pick the best match. If ambiguous, ask.
+
+3. **Product details** (if needed) — run `vellum amazon product <asin> --json` to get full details including price and variations. For products with variants (size, color, etc.), see the Variations section below.
+
+4. **Add to cart** — run `vellum amazon cart add --asin <asin> [--quantity <n>] --json`. The response includes the updated cart with all items.
+
+5. **Review cart** — run `vellum amazon cart view --json` and show the user what's in their cart with prices. Ask if they want to add anything else or proceed.
+
+6. **Payment methods** — run `vellum amazon payment-methods --json` to see saved cards.
+
+7. **Checkout summary** — run `vellum amazon checkout --json` to get order totals (subtotal, shipping, tax, total).
+
+8. **Place order** — after the user explicitly confirms, run `vellum amazon order place [--payment-method-id <id>] --json`. The response contains `orderId` on success.
+
+## Typical Flow — Amazon Fresh Groceries
+
+Amazon Fresh delivers groceries. The flow is the same as regular Amazon, with these additions:
+
+1. **Search Fresh** — use the `--fresh` flag: `vellum amazon search "<query>" --fresh --json`
+
+2. **Add Fresh items** — use the `--fresh` flag: `vellum amazon cart add --asin <asin> --fresh --json`
+
+3. **Select delivery slot** — Fresh orders require a delivery window:
+   - `vellum amazon fresh delivery-slots --json` — list available slots
+   - `vellum amazon fresh select-slot --slot-id <id> --json` — select a slot
+   - Do this BEFORE checkout.
+
+4. **Checkout and order** — same as regular Amazon.
+
+## Handling Variations
+
+Many Amazon products (clothing, electronics) have variations (size, color, style):
+
+1. Run `vellum amazon product <asin> --json` to get the product and its `variations[]` array
+2. Each variation has: `dimensionName` (e.g. "size"), `value` (e.g. "Large"), `asin` (child ASIN), `isAvailable`, `priceValue`
+3. Use the child ASIN when adding to cart: `vellum amazon cart add --asin <child-asin> --json`
+
+Alternatively, run `vellum amazon variations <asin> --json` to list just the variations.
+
+## Important Behavior
+
+- **Always confirm before placing order.** Never call `order place` without explicit user approval. Show the cart and total first.
+- **Be proactive.** If the user says "order AA batteries", don't ask clarifying questions upfront — search, find the product, and suggest it. Only ask when you need a choice the user hasn't specified.
+- **Handle expired sessions gracefully.** If any command returns `"error": "session_expired"`, run `vellum amazon refresh --json` to re-capture the session.
+- **Handle extension errors.** If a command fails with a message about the browser extension not being connected, tell the user: "Please open Chrome, click the Vellum extension icon, and click Connect — then I'll retry." Do NOT try to interact with the relay directly.
+- **Show prices.** Always show prices when presenting products or the cart summary.
+- **Use `--json` flag** on all commands for reliable parsing.
+- **Do NOT use the browser skill.** All Amazon interaction goes through the CLI, not browser automation.
+- **Rate limiting.** Amazon may rate-limit rapid sequential requests. Wait 8–10 seconds between cart operations. If you get a 403 error, wait 15–20 seconds and retry.
+- **Always-allow tip.** At the start of an ordering flow, suggest the user enable "always allow" for `vellum amazon` commands: "Tip: You can type 'a' to always allow `vellum amazon` commands for this session so you won't be prompted each time."
+- **Fresh slot required.** Amazon Fresh orders require a delivery slot to be selected before checkout. If the user skips this step, remind them to run `vellum amazon fresh delivery-slots --json` and select a slot.
+
+## Command Reference
+
+```
+vellum amazon status --json                     # Check if logged in
+vellum amazon refresh --json                    # Capture fresh session via Ride Shotgun
+vellum amazon login --recording <path>          # Import session from a recording file
+vellum amazon logout                            # Clear session
+
+vellum amazon search "<query>" [--fresh] [--limit <n>] --json
+vellum amazon product <asin> [--fresh] --json
+vellum amazon variations <asin> --json
+
+vellum amazon cart view --json
+vellum amazon cart add --asin <asin> [--quantity <n>] [--fresh] --json
+vellum amazon cart remove --cart-item-id <id> --json
+
+vellum amazon fresh delivery-slots --json
+vellum amazon fresh select-slot --slot-id <id> --json
+
+vellum amazon payment-methods --json
+vellum amazon checkout --json
+vellum amazon order place [--payment-method-id <id>] [--slot-id <id>] --json
+```
+
+## Example Interactions
+
+**User**: "Order a pack of AA batteries from Amazon"
+
+1. `vellum amazon status --json` → logged in
+2. `vellum amazon search "AA batteries" --json` → finds products
+3. Show top results: "Duracell AA 20-pack ($12.99, Prime), Amazon Basics AA 48-pack ($14.49, Prime)..."
+4. User picks Duracell → `vellum amazon cart add --asin B00000J1ER --json`
+5. `vellum amazon cart view --json` → show cart summary
+6. `vellum amazon checkout --json` → show total
+7. "Your cart has 1x Duracell AA Batteries 20-pack ($12.99), total $12.99 with free Prime shipping. Ready to order?"
+8. User confirms → `vellum amazon order place --json`
+
+**User**: "Order a large blue t-shirt from Amazon"
+
+1. `vellum amazon search "blue t-shirt" --json` → finds products
+2. User picks a shirt → `vellum amazon variations <parentAsin> --json` → shows Size + Color combinations
+3. Find the child ASIN for Large + Blue → `vellum amazon cart add --asin <childAsin> --json`
+
+**User**: "Order milk and eggs from Amazon Fresh"
+
+1. `vellum amazon status --json` → logged in
+2. `vellum amazon search "whole milk" --fresh --json` → Fresh results
+3. `vellum amazon cart add --asin <milkAsin> --fresh --json`
+4. `vellum amazon search "eggs" --fresh --json` → Fresh results
+5. `vellum amazon cart add --asin <eggsAsin> --fresh --json`
+6. `vellum amazon fresh delivery-slots --json` → show available slots
+7. User picks a slot → `vellum amazon fresh select-slot --slot-id <id> --json`
+8. `vellum amazon checkout --json` → show totals
+9. User confirms → `vellum amazon order place --json`

package/src/config/bundled-skills/amazon/icon.svg

@@ -0,0 +1,13 @@
+<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+  <rect width="16" height="16" fill="#ffffff"/>
+  <rect x="2" y="3" width="12" height="9" fill="#FF9900" stroke="#232F3E" stroke-width="1"/>
+  <rect x="3" y="4" width="10" height="7" fill="#FF9900"/>
+  <rect x="4" y="5" width="2" height="2" fill="#232F3E"/>
+  <rect x="7" y="5" width="2" height="2" fill="#232F3E"/>
+  <rect x="10" y="5" width="2" height="2" fill="#232F3E"/>
+  <rect x="4" y="8" width="2" height="2" fill="#232F3E"/>
+  <rect x="7" y="8" width="2" height="2" fill="#232F3E"/>
+  <rect x="10" y="8" width="2" height="2" fill="#232F3E"/>
+  <path d="M 3 13 Q 8 14 13 13" stroke="#232F3E" stroke-width="1" fill="none"/>
+  <rect x="2" y="13" width="12" height="1" fill="#232F3E"/>
+</svg>

package/src/config/bundled-skills/api-mapping/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: "API Mapping"
+description: "Record and analyze API surfaces of web services"
+user-invocable: true
+metadata: {"vellum": {"emoji": "🗺️"}}
+---
+
+You can record and analyze the API surface of any web service using the `map` CLI.
+
+## CLI Setup
+
+**IMPORTANT: Always use `host_bash` (not `bash`) for all `map` commands.** The API mapping CLI needs host access for Chrome CDP, network recording, and browser automation — none of which are available inside the sandbox.
+
+`map` is a standalone CLI tool installed at `~/.vellum/bin/map`. It should already be on your PATH. If `map` is not found, prepend `PATH="$HOME/.vellum/bin:$PATH"` to the command. Do NOT search for the binary or try to discover how the CLI works. Just run the commands as documented below.
+
+## Typical Flow
+
+When the user wants to map a web service's API (e.g. "Map the Notion API" or "Figure out how Figma's API works"):
+
+1. **Ask about the objective** — Ask the user: "What service do you want to map?" and "What are you trying to build or integrate with?" This helps focus the recording on the relevant parts of the API surface.
+
+2. **Choose mode** — Ask the user: "Should I browse automatically, or do you want to drive?" This determines whether to use auto mode or manual mode:
+   - **Auto mode**: The CLI launches a headless browser, navigates the service, and records API calls automatically. Best for broad discovery.
+   - **Manual mode**: A Chrome window opens for the user to interact with the service while the CLI records all API traffic in the background. Best for capturing a specific workflow.
+
+3. **Run the mapping** — Execute the appropriate `map` command:
+   - Auto mode: `map <domain> --json`
+   - Manual mode: `map <domain> --manual --json`
+   - For longer sessions: `map <domain> --duration 120 --json`
+
+4. **Wait for recording to complete** — In auto mode, the CLI will browse and record for the default duration (60 seconds) then stop. In manual mode, the CLI blocks until the user closes the browser or presses Ctrl+C. The command outputs a JSON summary of all discovered endpoints.
+
+5. **Analyze the API map** — Review the output and present findings to the user:
+   - List discovered endpoints grouped by resource type (e.g., `/api/v1/users`, `/api/v1/documents`)
+   - Note authentication patterns (Bearer tokens, cookies, API keys)
+   - Identify CRUD operations and their HTTP methods
+   - Highlight any WebSocket or streaming endpoints
+   - Call out rate limiting headers or pagination patterns
+
+6. **Offer next steps** — Based on the discovered API surface, offer to:
+   - Create CLI tools that wrap the discovered endpoints
+   - Generate TypeScript types from observed request/response payloads
+   - Build a focused integration for the user's specific use case
+   - Re-record with a longer duration or manual mode to capture more endpoints
+
+## Important Behavior
+
+- **Be proactive.** If the user names a service, start mapping immediately rather than asking unnecessary clarifying questions. Ask about mode preference, then go.
+- **Always use `--json` flag** on all commands for reliable parsing.
+- **Present findings clearly.** Group endpoints logically, show HTTP methods, and highlight the most useful ones for the user's stated objective.
+- **Suggest manual mode for authenticated services.** If auto mode returns mostly auth redirects or login pages, suggest switching to manual mode so the user can log in first.
+- **Handle errors gracefully.** If the domain is unreachable or the recording captures no API calls, suggest checking the domain, trying manual mode, or increasing the duration.
+
+## Command Reference
+
+```
+map <domain> --json                        # Auto mode: browse and record API calls (default 60s)
+map <domain> --manual --json               # Manual mode: user drives the browser, CLI records
+map <domain> --duration <secs> --json      # Auto mode with custom duration
+map <domain> --manual --duration <secs> --json  # Manual mode with custom timeout
+```
+
+## Example Interaction
+
+**User**: "Map the Notion API"
+
+1. Ask: "What are you trying to build with Notion? And should I browse automatically, or do you want to drive the browser?"
+2. User says: "I want to build a CLI to manage my pages. I'll drive."
+3. `map notion.com --manual --json` -> Chrome window opens
+4. Tell user: "A Chrome window is open. Log into Notion and do a representative workflow — create a page, edit it, maybe move it. I'll record all API calls in the background. Close the browser when you're done."
+5. User closes browser -> CLI outputs discovered endpoints
+6. Present findings: "I found 14 API endpoints. Here are the key ones for page management:
+   - `POST /api/v3/getSpaces` — lists workspaces
+   - `POST /api/v3/syncRecordValues` — fetches page content
+   - `POST /api/v3/submitTransaction` — creates/updates pages
+   - `POST /api/v3/enqueueTask` — async operations (export, duplicate)
+   Authentication: Cookie-based session with `token_v2`."
+7. Offer: "Want me to create a CLI tool that wraps these endpoints for managing Notion pages?"

package/src/config/bundled-skills/browser/SKILL.md

@@ -17,6 +17,7 @@ Use this skill to browse the web. After loading this skill, the following browse
 - `browser_press_key` — Press a keyboard key
 - `browser_wait_for` — Wait for a condition
 - `browser_extract` — Extract page text content
+- `browser_wait_for_download` — Wait for a file download to complete
 - `browser_fill_credential` — Fill a stored credential into a form field
 
 ## Typical Workflow

package/src/config/bundled-skills/browser/TOOLS.json

@@ -196,6 +196,23 @@
       "executor": "tools/browser-extract.ts",
       "execution_target": "host"
     },
+    {
+      "name": "browser_wait_for_download",
+      "description": "Wait for a file download to complete on the current page. Use after clicking a download button or link. Returns the filename and local file path.",
+      "category": "browser",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "timeout": {
+            "type": "number",
+            "description": "Maximum wait time in milliseconds (default: 30000, max: 120000)."
+          }
+        }
+      },
+      "executor": "tools/browser-wait-for-download.ts",
+      "execution_target": "host"
+    },
     {
       "name": "browser_fill_credential",
       "description": "Fill a stored credential into a form field without exposing the value. Target by element_id (from browser_snapshot) or CSS selector.",

package/src/config/bundled-skills/browser/tools/browser-wait-for-download.ts

@@ -0,0 +1,25 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import { browserManager } from '../../../../tools/browser/browser-manager.js';
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const timeout = typeof input.timeout === 'number'
+    ? Math.min(Math.max(input.timeout, 1000), 120_000)
+    : 30_000;
+
+  try {
+    const download = await browserManager.waitForDownload(context.sessionId, timeout);
+    return {
+      content: JSON.stringify({
+        filename: download.filename,
+        path: download.path,
+      }),
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

package/src/config/bundled-skills/doordash/SKILL.md

@@ -5,62 +5,62 @@ user-invocable: true
 metadata: {"vellum": {"emoji": "\uD83C\uDF55"}}
 ---
 
-You can order food from DoorDash for the user using the `vellum doordash` CLI.
+You can order food from DoorDash for the user using the `doordash` CLI.
 
 ## CLI Setup
 
-**IMPORTANT: Always use `host_bash` (not `bash`) for all `vellum doordash` commands.** The DoorDash CLI needs host access for Chrome CDP, session cookies, and the `vellum` binary — none of which are available inside the sandbox.
+**IMPORTANT: Always use `host_bash` (not `bash`) for all `doordash` commands.** The DoorDash CLI needs host access for Chrome CDP, session cookies, and the CLI binary — none of which are available inside the sandbox.
 
-`vellum doordash` is a built-in subcommand of the Vellum assistant CLI — it is NOT a separate tool you need to find or install. It should already be on your PATH. If `vellum` is not found, prepend `PATH="$HOME/.local/bin:$PATH"` to the command. Do NOT search for the binary, inspect wrapper scripts, or try to discover how the CLI works. Just run the commands as documented below.
+`doordash` is a standalone CLI tool installed at `~/.vellum/bin/doordash`. It should already be on your PATH. If `doordash` is not found, prepend `PATH="$HOME/.vellum/bin:$PATH"` to the command. Do NOT search for the binary, inspect wrapper scripts, or try to discover how the CLI works. Just run the commands as documented below.
 
 ## Task Progress Widget
 
-A task progress card is shown automatically when you run your first `vellum doordash` command. Its surface ID is `doordash-progress`. As each step completes, call `ui_update` with surface ID `doordash-progress` to update step statuses. Update `data.templateData.steps` — set completed steps to `"status": "completed"` with a `"detail"` string, the current step to `"status": "in_progress"`, and future steps to `"status": "pending"`. Adapt the steps to the actual flow (e.g. skip "Search restaurants" if the user named a specific store).
+A task progress card is shown automatically when you run your first `doordash` command. Its surface ID is `doordash-progress`. As each step completes, call `ui_update` with surface ID `doordash-progress` to update step statuses. Update `data.templateData.steps` — set completed steps to `"status": "completed"` with a `"detail"` string, the current step to `"status": "in_progress"`, and future steps to `"status": "pending"`. Adapt the steps to the actual flow (e.g. skip "Search restaurants" if the user named a specific store).
 
 ## Typical Flow
 
 When the user asks you to order food (e.g. "Order pizza from Andiamo's"):
 
-1. **Check session** — run `vellum doordash status --json`. If `loggedIn` is false or the session is expired, tell the user: "A Chrome window will open to the DoorDash login page. Please sign in there — I'll detect your login automatically and minimize the window." Then run `vellum doordash refresh --json`. This starts a Ride Shotgun learn session that records your login and auto-stops once it detects you've signed in. The session is imported automatically. **This command blocks until login is complete — just wait for it.**
+1. **Check session** — run `doordash status --json`. If `loggedIn` is false or the session is expired, tell the user: "A Chrome window will open to the DoorDash login page. Please sign in there — I'll detect your login automatically and minimize the window." Then run `doordash refresh --json`. This starts a Ride Shotgun learn session that records your login and auto-stops once it detects you've signed in. The session is imported automatically. **This command blocks until login is complete — just wait for it.**
 
    Keep the DoorDash Chrome window open in the background — it's needed for API requests.
 
-2. **Search** — run `vellum doordash search "<query>" --json` to find matching restaurants. Present the top results to the user with name, rating, and delivery info. If the user named a specific restaurant, pick the best match. If ambiguous, ask.
+2. **Search** — run `doordash search "<query>" --json` to find matching restaurants. Present the top results to the user with name, rating, and delivery info. If the user named a specific restaurant, pick the best match. If ambiguous, ask.
 
-3. **Browse menu** — run `vellum doordash menu <storeId> --json` to get the menu. Show the user the categories and items with prices. If the user already said what they want (e.g. "pepperoni pizza"), find the matching item(s). **For convenience/pharmacy stores** (CVS, Duane Reade, Walgreens etc.), the response will have `isRetail: true` and empty items — use `store-search` instead (see step 3b).
+3. **Browse menu** — run `doordash menu <storeId> --json` to get the menu. Show the user the categories and items with prices. If the user already said what they want (e.g. "pepperoni pizza"), find the matching item(s). **For convenience/pharmacy stores** (CVS, Duane Reade, Walgreens etc.), the response will have `isRetail: true` and empty items — use `store-search` instead (see step 3b).
 
-3b. **Search within a retail store** — for convenience/pharmacy stores, run `vellum doordash store-search <storeId> "<query>" --json` to find specific products. This returns items with IDs, prices, and menuIds that can be added to cart directly.
+3b. **Search within a retail store** — for convenience/pharmacy stores, run `doordash store-search <storeId> "<query>" --json` to find specific products. This returns items with IDs, prices, and menuIds that can be added to cart directly.
 
-4. **Get item details** (if needed) — run `vellum doordash item <storeId> <itemId> --json` to see options/customizations. The response includes:
+4. **Get item details** (if needed) — run `doordash item <storeId> <itemId> --json` to see options/customizations. The response includes:
    - `options`: each option group has `minSelections`/`maxSelections` indicating how many choices are required
    - Each choice has `unitAmount` (price impact in cents), `defaultQuantity`, and possibly `nestedOptions` (sub-choices like milk type within a size selection)
    - `specialInstructionsConfig`: whether special instructions are accepted, max length, and placeholder text
 
    If the item has required options (like size or toppings), construct the `nestedOptions` JSON from the option/choice IDs and pass it via `--options`. Ask the user for preferences or pick sensible defaults.
 
-5. **Add to cart** — run `vellum doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "<name>" --unit-price <cents> [--options '<json>'] [--special-instructions "<text>"] --json`. For subsequent items at the same store, pass `--cart-id <id>` from the first add response. Use `--special-instructions` for requests like "extra hot", "no ice", etc. Use `--options` to pass customization choices (see Customization Options below).
+5. **Add to cart** — run `doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "<name>" --unit-price <cents> [--options '<json>'] [--special-instructions "<text>"] --json`. For subsequent items at the same store, pass `--cart-id <id>` from the first add response. Use `--special-instructions` for requests like "extra hot", "no ice", etc. Use `--options` to pass customization choices (see Customization Options below).
 
-6. **Review cart** — run `vellum doordash cart view <cartId> --json` and show the user what's in their cart with prices. Ask if they want to add anything else or proceed.
+6. **Review cart** — run `doordash cart view <cartId> --json` and show the user what's in their cart with prices. Ask if they want to add anything else or proceed.
 
-7. **Checkout** — run `vellum doordash checkout <cartId> --json` to get delivery options. Present them to the user.
+7. **Checkout** — run `doordash checkout <cartId> --json` to get delivery options. Present them to the user.
 
-8. **Payment methods** — run `vellum doordash payment-methods --json` to see saved cards. Show the user which card will be used (the default one).
+8. **Payment methods** — run `doordash payment-methods --json` to see saved cards. Show the user which card will be used (the default one).
 
-9. **Place order** — after the user explicitly confirms, run `vellum doordash order place --cart-id <id> --store-id <id> --total <cents> [--tip <cents>] [--dropoff-option <id>] --json`. The command auto-selects the default payment method if `--payment-uuid` is not provided. The response contains `orderUuid` on success.
+9. **Place order** — after the user explicitly confirms, run `doordash order place --cart-id <id> --store-id <id> --total <cents> [--tip <cents>] [--dropoff-option <id>] --json`. The command auto-selects the default payment method if `--payment-uuid` is not provided. The response contains `orderUuid` on success.
 
 ## Important Behavior
 
 - **Always confirm before checkout.** Never place an order without explicit user approval.
 - **Be proactive.** If the user says "order pizza from Andiamo's", don't ask clarifying questions upfront — search, find the store, show the menu, and suggest items. Only ask when you need a choice the user hasn't specified.
-- **Handle expired sessions gracefully.** If any command returns `"error": "session_expired"`, run `vellum doordash refresh --json` to re-capture the session.
+- **Handle expired sessions gracefully.** If any command returns `"error": "session_expired"`, run `doordash refresh --json` to re-capture the session.
 - **Show prices.** Always show prices when presenting items or the cart summary.
 - **Use `--json` flag** on all commands for reliable parsing.
 - **Do NOT use the browser skill.** All DoorDash interaction goes through the CLI, not browser automation.
-- **Rate limiting.** DoorDash rate-limits rapid sequential requests. When adding multiple items (e.g. a team order), wait 8–10 seconds between `cart add` calls. If you get a 403 error, wait 15–20 seconds and retry. For large orders (5+ items), consider running `vellum doordash refresh --json` midway through if you hit repeated 403s.
+- **Rate limiting.** DoorDash rate-limits rapid sequential requests. When adding multiple items (e.g. a team order), wait 8–10 seconds between `cart add` calls. If you get a 403 error, wait 15–20 seconds and retry. For large orders (5+ items), consider running `doordash refresh --json` midway through if you hit repeated 403s.
 - **Special instructions are unreliable.** Some merchants disable special instructions entirely. Always prefer `--options` for customizations (size, milk type, etc.). Only use `--special-instructions` for free-text requests that aren't covered by the item's option groups. If the merchant rejects special instructions, drop them and proceed without.
 - **Customization fallback.** If `cart add` with `--options` fails, or if the item details show options that are hard to construct (deeply nested, unusual format), proactively offer to use `cart learn` so the user can customize the item visually in the browser. Don't silently drop customizations — tell the user what happened and offer alternatives.
-- **Always-allow tip.** At the start of an ordering flow, suggest the user enable "always allow" for `vellum doordash` commands: "Tip: You can type 'a' to always allow `vellum doordash` commands for this session so you won't be prompted each time."
-- **Error attribution.** When errors occur, assume it's more likely a bug in our query/parsing than a DoorDash API change. Suggest running `vellum doordash record` to capture fresh queries before assuming the schema changed.
+- **Always-allow tip.** At the start of an ordering flow, suggest the user enable "always allow" for `doordash` commands: "Tip: You can type 'a' to always allow `doordash` commands for this session so you won't be prompted each time."
+- **Error attribution.** When errors occur, assume it's more likely a bug in our query/parsing than a DoorDash API change. Suggest running `doordash record` to capture fresh queries before assuming the schema changed.
 
 ## Customization Options
 
@@ -68,7 +68,7 @@ Many items (especially coffee, boba, sandwiches) have required customization opt
 
 ### Constructing nestedOptions JSON
 
-1. Run `vellum doordash item <storeId> <itemId> --json` to get the item's option groups
+1. Run `doordash item <storeId> <itemId> --json` to get the item's option groups
 2. Each option group has `id`, `name`, `required`, `minSelections`, `maxSelections`, and `choices`
 3. Build a JSON array of selections matching the DoorDash format:
 
@@ -97,67 +97,67 @@ Use `--special-instructions` on `cart add` for free-text requests like "extra ho
 
 For complex items where constructing the JSON manually is difficult, use `cart learn`:
 
-1. Run `vellum doordash cart learn --json`
+1. Run `doordash cart learn --json`
 2. A Chrome window opens — navigate to the item, customize it visually, and click "Add to Cart"
 3. The command auto-detects the `updateCartItem` operation and extracts the exact `nestedOptions` and `specialInstructions`
 4. Use the extracted options directly with `cart add --options '<json>'`
 
-You can also extract options from an existing recording with `vellum doordash inspect <recordingId> --extract-options --json`.
+You can also extract options from an existing recording with `doordash inspect <recordingId> --extract-options --json`.
 
 ### Coffee Order Example
 
 **User**: "Order a large oat milk latte with an extra shot from Blue Bottle"
 
-1. `vellum doordash search "Blue Bottle" --json` -> finds store
-2. `vellum doordash menu <storeId> --json` -> finds "Latte" item
-3. `vellum doordash item <storeId> <latteItemId> --json` -> returns options:
+1. `doordash search "Blue Bottle" --json` -> finds store
+2. `doordash menu <storeId> --json` -> finds "Latte" item
+3. `doordash item <storeId> <latteItemId> --json` -> returns options:
    - Size (required, min:1, max:1): Small (id:101), Medium (id:102), Large (id:103, +$1.00)
    - Milk (required, min:1, max:1): Whole (id:201), Oat (id:202, +$0.70), Almond (id:203, +$0.70)
    - Extras (optional, min:0, max:5): Extra Shot (id:301, +$0.90), Vanilla Syrup (id:302, +$0.60)
 4. Construct options JSON and add to cart:
 ```
-vellum doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "Latte" --unit-price 550 --options '[{"optionId":"size-group-id","optionChoiceId":"103","quantity":1,"nestedOptions":[]},{"optionId":"milk-group-id","optionChoiceId":"202","quantity":1,"nestedOptions":[]},{"optionId":"extras-group-id","optionChoiceId":"301","quantity":1,"nestedOptions":[]}]' --special-instructions "Extra hot" --json
+doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "Latte" --unit-price 550 --options '[{"optionId":"size-group-id","optionChoiceId":"103","quantity":1,"nestedOptions":[]},{"optionId":"milk-group-id","optionChoiceId":"202","quantity":1,"nestedOptions":[]},{"optionId":"extras-group-id","optionChoiceId":"301","quantity":1,"nestedOptions":[]}]' --special-instructions "Extra hot" --json
 ```
 
 ## Command Reference
 
 ```
-vellum doordash status --json              # Check if logged in
-vellum doordash refresh --json             # Capture fresh session via Ride Shotgun (auto-stops after login)
-vellum doordash login --recording <path>   # Import session from a recording file manually
-vellum doordash logout --json              # Clear session
-vellum doordash search "<query>" --json    # Search restaurants
-vellum doordash menu <storeId> --json      # Get store menu (auto-detects retail stores)
-vellum doordash store-search <storeId> "<query>" --json  # Search items within a convenience/pharmacy store
-vellum doordash item <storeId> <itemId> --json  # Get item details + options
-vellum doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "<name>" --unit-price <cents> [--quantity <n>] [--cart-id <id>] [--options '<json>'] [--special-instructions "<text>"] --json
-vellum doordash cart remove --cart-id <id> --item-id <orderItemId> --json
-vellum doordash cart view <cartId> --json
-vellum doordash cart list [--store-id <id>] --json
-vellum doordash cart learn --json                 # Learn customization options by recording browser interaction
-vellum doordash inspect <recordingId> --extract-options --json  # Extract nestedOptions from a recording
-vellum doordash checkout <cartId> [--address-id <id>] --json
-vellum doordash payment-methods --json     # List saved payment methods
-vellum doordash order place --cart-id <id> --store-id <id> --total <cents> [--tip <cents>] [--delivery-option <type>] [--dropoff-option <id>] [--payment-uuid <uuid>] --json
+doordash status --json              # Check if logged in
+doordash refresh --json             # Capture fresh session via Ride Shotgun (auto-stops after login)
+doordash login --recording <path>   # Import session from a recording file manually
+doordash logout --json              # Clear session
+doordash search "<query>" --json    # Search restaurants
+doordash menu <storeId> --json      # Get store menu (auto-detects retail stores)
+doordash store-search <storeId> "<query>" --json  # Search items within a convenience/pharmacy store
+doordash item <storeId> <itemId> --json  # Get item details + options
+doordash cart add --store-id <id> --menu-id <id> --item-id <id> --item-name "<name>" --unit-price <cents> [--quantity <n>] [--cart-id <id>] [--options '<json>'] [--special-instructions "<text>"] --json
+doordash cart remove --cart-id <id> --item-id <orderItemId> --json
+doordash cart view <cartId> --json
+doordash cart list [--store-id <id>] --json
+doordash cart learn --json                 # Learn customization options by recording browser interaction
+doordash inspect <recordingId> --extract-options --json  # Extract nestedOptions from a recording
+doordash checkout <cartId> [--address-id <id>] --json
+doordash payment-methods --json     # List saved payment methods
+doordash order place --cart-id <id> --store-id <id> --total <cents> [--tip <cents>] [--delivery-option <type>] [--dropoff-option <id>] [--payment-uuid <uuid>] --json
 ```
 
 ## Example Interaction
 
 **User**: "Order a pepperoni pizza from Andiamo's"
 
-1. `vellum doordash status --json` -> logged in
-2. `vellum doordash search "Andiamo's" --json` -> finds store 22926474
-3. `vellum doordash menu 22926474 --json` -> finds "Pepperoni Pizza Pie" (item 2956709006, $28.00)
+1. `doordash status --json` -> logged in
+2. `doordash search "Andiamo's" --json` -> finds store 22926474
+3. `doordash menu 22926474 --json` -> finds "Pepperoni Pizza Pie" (item 2956709006, $28.00)
 4. Tell user: "I found Pepperoni Pizza Pie at Andiamo's for $28.00. Adding it to your cart."
-5. `vellum doordash cart add --store-id 22926474 --menu-id 12847574 --item-id 2956709006 --item-name "Pepperoni Pizza Pie" --unit-price 2800 --json`
-6. `vellum doordash cart view <cartId> --json` -> show summary
+5. `doordash cart add --store-id 22926474 --menu-id 12847574 --item-id 2956709006 --item-name "Pepperoni Pizza Pie" --unit-price 2800 --json`
+6. `doordash cart view <cartId> --json` -> show summary
 7. "Your cart has 1x Pepperoni Pizza Pie ($28.00), total $28.00. Ready to check out?"
 
 **User**: "I need Tylenol from CVS"
 
-1. `vellum doordash status --json` -> logged in
-2. `vellum doordash search "CVS" --json` -> finds store 1231787
-3. `vellum doordash menu 1231787 --json` -> isRetail: true, categories but no items
-4. `vellum doordash store-search 1231787 "tylenol" --json` -> finds results
+1. `doordash status --json` -> logged in
+2. `doordash search "CVS" --json` -> finds store 1231787
+3. `doordash menu 1231787 --json` -> isRetail: true, categories but no items
+4. `doordash store-search 1231787 "tylenol" --json` -> finds results
 5. Show top results: "Tylenol Extra Strength Gelcaps (24 ct) - $8.79, Tylenol Extra Strength Caplets (100 ct) - $13.49..."
 6. User picks one -> add to cart with the item's `id`, `menuId`, and `unitAmount`

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

@@ -31,13 +31,22 @@ vellum email create <your-username>
 
 For `<your-username>`, use your assistant name (lowercased, alphanumeric only). Check your identity from `IDENTITY.md` or `USER.md` to determine your name. If you don't have a name yet, ask the user what username they'd like for your email.
 
-## Step 3: Confirm Setup
+## Step 3: Persist Your Email
 
-After the inbox is created successfully:
+After the inbox is created successfully, persist your email address to the workspace config so the desktop app can display it:
 
-1. Parse the command output to extract your new email address.
-2. Tell the user your new email address.
-3. Store a note in your memory or `USER.md` that your email has been provisioned so you remember it in future conversations.
+```bash
+vellum config set email.address <your-new-email-address>
+```
+
+Replace `<your-new-email-address>` with the full email address returned from the create command (e.g. `sam@agentmail.to`).
+
+## Step 4: Confirm Setup
+
+After the inbox is created and persisted:
+
+1. Tell the user your new email address.
+2. Store a note in your memory or `USER.md` that your email has been provisioned so you remember it in future conversations.
 
 ## Rules