Vercel Token Setup

You are helping your user set up a Vercel API token so they can publish apps to the web.

Client Check

Determine whether the user has browser automation available (macOS desktop app) or is on a non-interactive channel (Telegram, Slack, etc.).

• macOS desktop app: Follow the Automated Setup path below.
• Telegram or other channel (no browser automation): Follow the Manual Setup for Channels path below.

Path A: Manual Setup for Channels (Telegram, Slack, etc.)

When the user is on Telegram or any non-macOS client, walk them through a text-based setup. No browser automation is used - the user follows links and performs each action manually.

Channel Step 1: Confirm and Explain

Tell the user:

Setting up Vercel API Token

Since I can't automate the browser from here, I'll walk you through each step with direct links. You'll need:

1. A Vercel account (free tier works)
2. About 2 minutes

Ready to start?

If the user declines, acknowledge and stop.

Channel Step 2: Create the Token

Tell the user:

Step 1: Create an API token

Open this link to go to your Vercel tokens page: https://vercel.com/account/tokens

1. Click "Create" (or "Create Token")
2. Set the token name to "Vellum Assistant"
3. Select scope: "Full Account"
4. Set expiration to the longest option available (or "No Expiration" if offered)
5. Click "Create Token"

A token value will appear - copy it now, as it's only shown once.

Channel Step 3: Store the Token

Tell the user:

Step 2: Send me the token

Please paste the token value into the secure prompt below.

Present the secure prompt (via the bash tool) — it collects the token through a secure UI and stores it with the right tool policy in one step:

assistant credentials prompt --service vercel --field api_token \
  --label "Vercel API Token" \
  --placeholder "Enter your Vercel API token" \
  --description "Paste the API token you just created on vercel.com" \
  --allowed-tools "publish_page,unpublish_page"

Channel Step 4: Done!

Vercel is connected! You can now publish apps to the web. Try clicking Publish on any app you've built.

Path B: Automated Setup (macOS Desktop App)

You will automate Vercel token creation via the browser while the user watches. The user's only manual action is signing in to Vercel (if needed) and one copy-paste for the token value.

Browser Interaction Principles

All browser operations are executed through the assistant browser CLI, invoked via host_bash. Vercel's UI may change over time. 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 screenshot to see the current visual state. Use assistant browser snapshot to find interactive elements.

   assistant browser --session vercel screenshot --output /tmp/vercel-state.jpg
   assistant browser --session vercel --json snapshot

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.

3. Verify after every action. After clicking, typing, or navigating, take a new screenshot to confirm the action succeeded.

4. Never assume DOM structure. 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.

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.
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.

Things That Do Not Work - Do Not Attempt

These actions are technically impossible in the browser automation environment:

• Downloading files. Clicking a Download button via assistant browser click does not save files to disk.
• Reading the token value from a screenshot. The token 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 assistant credentials prompt approach to let the user copy-paste it accurately.
• Clipboard operations. You cannot copy/paste via browser automation.

Step 1: Single Upfront Confirmation

Tell the user:

Setting up your Vercel API token so we can publish your app...

Here's what will happen:

1. A browser opens to your Vercel account settings
2. You sign in (if not already signed in)
3. I create the token - you just watch
4. One quick copy-paste - I'll ask you to copy the token value into a secure prompt

Takes about a minute. Ready?

If the user declines, acknowledge and stop. No further confirmations are needed after this point.