Docdeploymill://docs/upgrading

Upgrading from Explore to Builder

This is the page an upgrade_required (or any entitlement-gated) tool result points you at. You, the agent, hit a capability that the user's current plan doesn't include. This page tells you exactly what the free tier contains, what a card unlocks, and the precise next step. You never handle the card. Your job is to explain what unlocks and hand the human the upgrade link.

How to present this to the user (do this, in order)

Say what they hit. Name the specific capability the gate refused (e.g. "custom domains", "the REST API", "object storage", "editing the Dockerfile / build recipe"). The gate's error message and code tell you which one.
Say what unlocks. Adding a card flips on the whole set below at once, not just the one thing they hit. Mention that, because it usually changes the calculus.
Give them the link. If the gate payload included an upgradeUrl, hand the human that link and tell them to add a card there. If there's no upgradeUrl (billing not wired in this deployment), tell them upgrading isn't self-serve here yet and they should contact the operator. Do not invent a URL.
Stop. Do not ask for card details. Do not try to enter payment information. The card hand-off is the human's, in their browser, the same way secrets never reach you.

The plans

Plan	Price	Who it's for
Explore	Free, no card	A contained discovery surface: try the product, watch your agent build an app. Not for real workloads.
Builder	$10/mo minimum (card on file), includes your first $10 of usage	Real apps: the whole envelope below lifts on at once. After the floor you pay only for the hours your apps are actually awake, and a sleeping app costs nothing.
Enterprise	Sales-led	SSO + priority support on top of Builder, for teams with those needs.

What free Explore contains (and its limits)

Explore is deliberately contained: a place to see your agent rebuild an app, not a tier for production. On Explore you get:

1 app, from a curated template only (no arbitrary import of an existing repo).
No persistent storage. App state must live in the managed database, not on a volume.
1 seat.
The MCP endpoint (POST /mcp) and app-source edits stay open, so the user can keep watching their agent change the app and redeploy. The deploy loop over MCP is never trapped behind a paywall.

What Explore does not include (each of these is its own upgrade_required gate):

Custom domains. Explore apps are subdomain-only.
The REST API (/api/v1) and API keys, the headless/automation surface. (Drive the app with your agent over MCP instead while on free.)
Object storage (managed S3/R2 buckets).
Open egress. Outbound network is locked down on free.
Editing the build recipe. The Dockerfile / build config is locked on free (you may still edit app source and redeploy).
Custom templates and arbitrary import of an existing repo.

Plus conservative build rate caps.

What a card lifts on, all at once

The moment the user adds a card (the $10/mo Builder base, or any paid add-on), the entire contained envelope flips on together. There is no à-la-carte "just custom domains" toggle on the base. One card unlocks all of:

Custom domains (attach a domain the user owns).
The REST API + API keys (programmatic/headless access for scripts and CI).
Object storage (managed buckets).
Open egress (unlocked outbound networking).
An editable build recipe (the agent may edit the Dockerfile / build config).
Custom templates.
Arbitrary import of an existing repo (import_repo on a repo the platform didn't scaffold).

(SSO and priority support are the exceptions: they're Enterprise-only and are not unlocked by simply adding a card.)

So when a user balks at upgrading for the one thing they hit, remind them they're unlocking the whole set, not paying $10 for a single feature. The $10/mo minimum includes their first $10 of metered uptime usage, so a couple of mostly-sleeping apps rarely cost more than the floor.

The exact next step

If the gate gave you an upgradeUrl: tell the user to open it and add a card. That's the entire action: once the card is on file the gate clears and you can retry the refused tool call.
If there's no upgradeUrl: billing isn't self-serve in this deployment. Tell the user upgrading requires the operator, and surface whatever support/contact path the deployment documents. Don't fabricate a link.

After the user confirms they've added a card, retry the original tool call. The entitlement resolver picks up the new state, and the capability that was gated will now succeed.