# Payments and spend authority

Updated: 2026-08-31

VibeCord follows paid-before-spend. A provider job must not start unless the
account has enough admitted paid entitlement or reserved budget to cover the
maximum expected variable cost of that exact action.

## What internal dogfood agents can do today

When the internal MCP and PAT flags are enabled, an authenticated dogfood agent
can read the account's plan or usage summary and submit a gated VibeCord
operation. This is not a public agent-payment capability. The resulting
receipt may admit the action or deny it with a code such as `payment_required`
or `server_unit_budget_missing`.

The typed `billing.checkout.request` and `billing.entitlement.status` contracts
and common action handlers exist in source. Checkout returns a human-owner
handoff reference without creating a Stripe session or spend authority. A
signed-in review route is mounted in source; its checkout POST accepts only the
opaque `handoffId`, while the server revalidates the owner-bound receipt,
canonical offer, workload scope, and configured Stripe price. The agent request
still creates no payment session or spend authority, and this source path is
not deployed or release-proven. The CLI has no autonomous account signup,
card entry, direct purchase, refund, or payment-method management. An agent
must not collect card details or treat a request to deploy as authority to buy
capacity.

## Human payment handoff

When payment is required:

1. Stop the spend-bearing action.
2. Show the account owner the requested workload, quoted or capped action, and
   denial receipt.
3. Direct the owner to the authenticated VibeCord billing or checkout surface.
4. Wait for the owner to complete payment and for VibeCord to report the
   resulting entitlement.
5. Re-read workload readiness or usage before retrying the same action.

Do not infer success from a browser redirect, payment page, screenshot, or the
owner saying payment was attempted. The action is payable only when the
control-plane receipt and authoritative entitlement state agree.

## Existing delegated budget

If an account owner has already established an explicit capped mandate or
prepaid entitlement, an agent may submit operations within the token scope and
that cap. VibeCord still decides each action independently. The agent must stop
when the receipt reports insufficient entitlement, capacity, proof, or lane
availability.

The typed checkout request selects one canonical configured `offerId` for one
exact project/workload, then requests a `human_owner` handoff. It does not
accept a client-supplied `quoteId` or charge a card. Exact maximum-COGS quoting
and reservation belong to later `deploy.request` admission, after authoritative
payment and entitlement readback. Reserve, settle, release, and refund server
flows now exist in source, including a signed provider-lifecycle callback, but
no provider emitter is connected and no production settlement or reconciliation
proof exists. They are not public functionality.

Use only offers returned by VibeCord's configured catalogue. `pro` is an
existing canonical plan offer. A four-hour Minecraft parked-world prepaid offer
is not yet catalogued or configured and needs an explicit price plus Stripe
Price ID decision before any agent or public example may request it.

## Required cost lifecycle

The intended hosted lifecycle is:

```text
quote maximum cost -> owner payment or capped mandate -> reserve -> provision
-> meter actual cost -> stop and verify teardown -> settle -> release unused reserve
```

No documentation, feature flag, plan label, or generated artifact is payment
proof. A successful local preview or export also does not authorize hosted
runtime spend.

Read [RECEIPTS.md](./RECEIPTS.md) for denial handling and
[AUTH.md](./AUTH.md) for the account-owner boundary.