jona62 · Oct 31, 2026 · Oct 5, 2026 · Oct 31, 2026 · Oct 31, 2026
diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@ Existing routes and heading anchors are inventoried in `scripts/legacy-routes.js
 python3 scripts/generate-cli-reference.py --check
 python3 scripts/build-navigation.py --check
 python3 scripts/check-docs.py
+python3 scripts/sync-paid-schemas.py --check
 npx mintlify@4.2.375 validate
 npx mintlify@4.2.375 broken-links
 ```
@@ -46,3 +47,36 @@ openapi: /openapi/rigbox-api.json GET /api/v1/workspaces
 Do not add top-level `openapi` to `docs.json`: Mintlify 4.2.375's file categorizer misidentifies that configuration as an API specification. Explicit page references resolve the strict validation warning. Native endpoints and playground contracts remain unchanged. App-release and volume definitions are copied from the recorded server specification. Builds/image-release routes absent from that specification remain covered by CLI guides; do not invent generated API definitions.
 
 The existing `sync-openapi.yml` workflow updates production specs. Review its output against the targeted release before incorporating it into the docs; newly split specifications also need deliberate refresh and coverage review. Contract changes belong in the server source, not hand edits to documentation schemas.
+
+## Paid pricing pages
+
+The pricing, limits, managed wallet and billing reference pages describe paid plans
+in the present tense. Whether paid pricing is live is decided in one place:
+`snippets/paid-pricing.mdx`, which every one of those pages imports and shows as
+`<PaidPricingStatus />`. It holds a comment and one `<Warning>` line, the rollout
+banner. **Going live is a one-line change: delete that `<Warning>` line.** No other
+page text needs to change. Keep the banner on one line, and don't wrap it in a
+condition: Mintlify 4.2.375 doesn't render an expression that contains a component
+inside an imported snippet, so `{live && <Warning>…}` silently shows nothing.
+
+`verification/paid-v1-schemas.json` holds the wallet and limits components copied
+from a gateway export, and `scripts/sync-paid-schemas.py` copies only those into
+`openapi/rigbox-api.json`, preserving unrelated gateway paths and schemas.
+`openapi/auth-api.json` is the complete auth-service export, checked against the
+SHA-256 recorded in `verification/paid-pricing.json`. Verify with `--check`.
+
+To refresh both from a rig-mvp revision, using its pinned toolchain (`rust-toolchain`):
+
+```bash
+# in rig-mvp/server; the example is a two-line harness around rig_auth::openapi(),
+# not committed there
+cargo run -p rig-gateway -- --print-openapi > /tmp/gateway.json
+cargo run -p rig-auth --example print_openapi > /tmp/auth-api.json
+```
+
+Then copy the four components into `verification/paid-v1-schemas.json`, replace
+`openapi/auth-api.json`, update the revision and hashes in
+`verification/paid-pricing.json`, and run `python3 scripts/sync-paid-schemas.py`.
+Several billing responses are generic JSON objects in the server source; don't
+invent typed shapes for them. A production sync from older binaries can bring back
+obsolete monthly-wallet wording: run the paid-schema check and review the diff.
diff --git a/ai/managed-wallet.mdx b/ai/managed-wallet.mdx
@@ -0,0 +1,83 @@
+---
+title: Managed AI wallet
+description: Managed AI wallet balance, durable reservations, exact charges, and verified renewal behavior.
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+Managed AI uses an account wallet shared by your workspaces. Paid compute plans include no AI credits. **1,000 credits represent approximately $10 of upstream usage.** An active paid subscriber may buy those credits as a **$13 pack**, whose price includes a 30% managed service markup on that upstream usage. [BYOK](/guides/byok) uses separate provider billing.
+
+## Read the wallet
+
+| Value | Meaning |
+| --- | --- |
+| Balance | Funds remaining after completed grants, charges, and adjustments, before open holds |
+| Reserved | Funds held for requests whose financial outcome is not yet finalized |
+| Available | Balance minus reserved funds; the amount available for new reservations |
+
+For example, a 100-credit balance with 12 credits reserved has 88 available credits. A reservation is not a final charge. When confirmed usage settles to 3 credits, the 12-credit hold is removed, the balance becomes 97, and available funds become 97 if no other holds exist.
+
+Billing shows the three values and the latest 100 ledger entries. Entries distinguish pack purchases, preserved opening funds, verified legacy paid-period grants, reservations, settled usage, cancellations, and adjustments. This is a combined wallet: historical labels do not establish a remaining purchased-versus-included spending split.
+
+Use the [credits API](/api-reference/ai/get-credits) or CLI for the available balance and balance before holds:
+
+```bash
+rig status
+rig api GET /v1/users/me/credits
+```
+
+`remaining` means available funds; `total` means balance before holds. Neither is a monthly allowance. Use the exact `remaining_micro` and `total_micro` integers for calculations: **1,000,000 microcredits = 1 credit**. Compatibility fields `free` and `free_micro` are zero; `pro` and `pro_micro` alias the available fields. They do not identify funding provenance.
+
+Older CLI versions can use historical bucket labels or round small values. The authenticated wallet projection and microcredit fields are authoritative. Do not use rounded text to authorize spending or hide a negative balance.
+
+## Reserve before forwarding
+
+Before forwarding a managed request, Rigbox atomically reserves an estimated cost in the primary wallet. Concurrent requests across workspaces cannot spend the same available funds. Missing output limits receive a compatible bound used for reservation and forwarding. Unknown pricing or unsupported bounded admission is refused before forwarding.
+
+A reservation estimates potential usage, not a quoted final price. A request can be refused because its estimate exceeds available funds even when a typical response would cost less. Lower the request's output bound, select a cheaper supported model, buy credits, or deliberately configure BYOK.
+
+When provider cost is confirmed, settlement removes the hold and records the actual debit exactly once. USD usage is converted to microcredits using `ceil(cost_usd × 100 × 1,000,000)`, preserving small nonzero charges. The pack's markup is not added again during settlement.
+
+Provider-confirmed zero usage settles to zero. A model named `free`, missing cost fields, an empty response, or a browser error is not proof of zero cost.
+
+## Interrupted or uncertain requests
+
+| Outcome | Wallet behavior |
+| --- | --- |
+| Confirmed completed usage | Settle the actual charge and remove the hold |
+| Explicit upstream rejection | Release the hold without charging that rejected request |
+| Interrupted stream, ambiguous transport failure, or incomplete usage | Keep the durable hold while the outcome is investigated |
+| Completed generation metadata recovered later | Settle once from confirmed usage |
+| Missing recoverable evidence | Retain the unresolved hold for operator review |
+
+The proxy retains bounded generation and usage metadata for reconciliation, not prompts, response content, search text, or credentials. Recovery is bounded and uses backoff; it has no promised completion deadline. A missing upstream generation identity may require operator investigation.
+
+Closing the connection or switching AI mode does not cancel a charge already incurred. Avoid automatically repeating a request after an uncertain outcome: the provider may have completed the first request, and a new request can incur another charge. Inspect Billing and your application logs first.
+
+Native Anthropic streaming follows this reservation and reconciliation contract too. Managed speech requires a supported bounded pricing model; binary response headers alone do not prove its charge. Use BYOK deliberately when the managed endpoint refuses unsupported pricing.
+
+## Debt, refunds, and disputes
+
+Confirmed usage that exceeds the reservation remains a debit. Refund or dispute adjustments can also make the balance or available funds negative. The ledger preserves that debt instead of truncating it to zero or discarding usage. New managed requests are refused when the wallet cannot fund their reservation.
+
+Refund and dispute records adjust the financial projection cumulatively and idempotently. A bank refund is not a fresh AI grant. If an adjustment or open hold looks incorrect, provide the affected operation or request identifier to support; do not assume a retry or new calendar month will clear it.
+
+Adjustment of a subscription payment can also revoke compute eligibility for the affected paid period while retaining resources. Winning a dispute can reverse its wallet adjustment cumulatively, but compute eligibility is not automatically restored: that requires operator review. Wallet funds and permission to run compute are separate projections.
+
+## Purchases and legacy renewals
+
+Credit-pack funds appear only after the purchase is verified and its durable operation is applied. A success URL alone does not confirm a grant. There is no automatic refill.
+
+At cutover, previously held funds are preserved as a non-expiring opening grant. Paid plans include no AI credits. Legacy Pro Managed retains a 2,000-credit grant for each uniquely verified paid subscription period. Duplicate or reordered payment events do not create duplicate grants. Failed or unfunded renewal does not create a grant; later verified payment can reconcile the eligible period once.
+
+Only eligible non-proration initial subscription or renewal periods with positive, verified provider-funded invoice evidence create that legacy grant. Zero-total or out-of-band paid labels are review-pending, not evidence of a grant.
+
+Wallet funds do not reset at the beginning of a calendar month. Unspent preserved and purchased funds remain in the wallet. Plan and mode changes do not erase them, and switching to BYOK does not release pending managed holds.
+
+## Exhausted credits
+
+Insufficient available funds produce HTTP `402` for new managed requests. Buy a pack while your paid plan is active or explicitly configure your provider endpoint and key for BYOK. Upgrading a new compute plan alone does not add credits.
+
+An AI wallet failure does not itself stop non-AI services. Separate compute entitlement, capacity, policy, or resource failures can still affect the workspace. [Resource limits](/concepts/limits) explains those prerequisites.
diff --git a/ai/overview.mdx b/ai/overview.mdx
@@ -5,6 +5,8 @@ description: "Run coding agents and developer services in a Rigbox workspace."
 
 Choose whether you need an interactive coding environment or an HTTP service. A CLI app has no public URL; connect over SSH and run its executable. A service app has a process, port, and health check.
 
+[Paid compute plans](/concepts/pricing-and-billing) include no AI credits. Choose separate managed credit purchases or BYOK provider billing. The [managed wallet](/ai/managed-wallet) distinguishes funds available for requests from pending holds and confirmed charges.
+
 ## Set up your environment
 
 1. [Create a workspace](/guides/workspaces) with the runtime your tool needs.

diff --git a/api-reference/ai/get-credits.mdx b/api-reference/ai/get-credits.mdx
@@ -3,3 +3,9 @@ title: Get AI Credits
 openapi: "/openapi/rigbox-api.json GET /api/v1/users/me/credits"
 description: "Get the authenticated user's AI credit balance and mode (managed or BYOK)."
 ---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+`remaining` is the funds available for requests and `total` is the balance before holds; neither is a monthly grant. The `_micro` fields carry exact microcredits. See [managed wallet](/ai/managed-wallet).
diff --git a/api-reference/ai/get-limits.mdx b/api-reference/ai/get-limits.mdx
@@ -3,3 +3,9 @@ title: Get User Limits
 openapi: "/openapi/rigbox-api.json GET /api/v1/users/me/limits"
 description: Get account plan limits including workspace, app, and resource caps.
 ---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+Alongside the limits and usage, the response carries the paid entitlement: `compute_allowed`, `entitlement_status`, `pricing_transition_until`, `billing_paid_through` and `billing_revision`. The account's sustained CPU budget is `limits.sustained_cpu_millis` against `usage.running_cpu_millis`; 1,000 millicores are one core of sustained CPU time. See [resource limits](/concepts/limits).
diff --git a/api-reference/billing/cancel-scheduled.mdx b/api-reference/billing/cancel-scheduled.mdx
@@ -0,0 +1,17 @@
+---
+title: Cancel a scheduled change
+openapi: "/openapi/auth-api.json POST /api/v1/auth/billing/change/cancel-scheduled"
+description: "Cancel a plan or add-on change scheduled for period end. Console only."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+**Console only.** This operation needs a signed-in console session; an API key or CLI login gets `404`. Use Billing in the console. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+Cancel a plan or add-on change that is scheduled for the end of the current period, so the confirmed subscription continues unchanged. A change that is no longer cancellable, because it already applied or nothing is scheduled, answers `409`. Cancelling does not resize, start, move, or restart a workspace.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.
diff --git a/api-reference/billing/catalog.mdx b/api-reference/billing/catalog.mdx
@@ -0,0 +1,17 @@
+---
+title: Billing catalog
+openapi: "/openapi/auth-api.json GET /api/v1/auth/billing/catalog"
+description: "Read the paid plans, add-ons and credit-pack prices. Readable with an API key."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+Readable with an API key, so scripts and `rig limits` / `rig whoami` can show billing state. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+Inspect the paid plan prices and account ceilings. Catalog visibility is not paid entitlement; `checkout_enabled` reflects configured availability. Price fields use USD cents. RAM and storage allowance amounts use MiB-sized units; CPU uses millicores. The source response schema is generic JSON, so use the confirmed account response rather than assuming missing fields.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.
diff --git a/api-reference/billing/change.mdx b/api-reference/billing/change.mdx
@@ -0,0 +1,17 @@
+---
+title: Change plan or add-ons
+openapi: "/openapi/auth-api.json POST /api/v1/auth/billing/change"
+description: "Change your plan or add-ons. Console only."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+**Console only.** This operation needs a signed-in console session; an API key or CLI login gets `404`. Use Billing in the console. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+Request a plan or add-on change using the authoritative loaded subscription and a durable UUID operation ID. Upgrades require verified payment; reductions must fit retained allocations. Pending changes leave the confirmed allowance in effect. A confirmed change does not resize, start, move, or restart a workspace.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.
diff --git a/api-reference/billing/create-checkout.mdx b/api-reference/billing/create-checkout.mdx
@@ -0,0 +1,17 @@
+---
+title: Create subscription checkout
+openapi: "/openapi/auth-api.json POST /api/v1/auth/create-checkout-session"
+description: "Start checkout for a paid plan. Console only."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+**Console only.** This operation needs a signed-in console session; an API key or CLI login gets `404`. Use Billing in the console. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+Choose a new paid plan with a durable UUID `operation_id` and permitted return URLs. Retry an ambiguous request with the same operation ID and intended purchase. A checkout URL or success redirect does not grant paid compute; wait for verified payment and confirmed account projection.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.
diff --git a/api-reference/billing/create-portal.mdx b/api-reference/billing/create-portal.mdx
@@ -0,0 +1,17 @@
+---
+title: Create billing portal session
+openapi: "/openapi/auth-api.json POST /api/v1/auth/create-portal-session"
+description: "Open the billing portal for payment methods, invoices and cancellation. Console only."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+**Console only.** This operation needs a signed-in console session; an API key or CLI login gets `404`. Use Billing in the console. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+Open the configured portal for payment methods, invoices, or period-end cancellation. Capacity-sensitive plan and add-on changes use the Rigbox Billing flow. Portal creation does not change entitlement. Only a permitted return URL is accepted.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.
diff --git a/api-reference/billing/credit-pack-checkout.mdx b/api-reference/billing/credit-pack-checkout.mdx
@@ -0,0 +1,17 @@
+---
+title: Create credit-pack checkout
+openapi: "/openapi/auth-api.json POST /api/v1/auth/billing/credit-packs/checkout"
+description: "Buy a managed AI credit pack. Console only."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+**Console only.** This operation needs a signed-in console session; an API key or CLI login gets `404`. Use Billing in the console. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+An active verified paid subscription is required to purchase optional managed AI credits. A $13 pack buys 1,000 credits representing approximately $10 of upstream usage, with 30% markup included in the pack price. The purchase is one-time; neither checkout creation nor return parameters grant wallet funds. Verify the durable operation before treating the grant as applied.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.
diff --git a/api-reference/billing/operation-status.mdx b/api-reference/billing/operation-status.mdx
@@ -0,0 +1,17 @@
+---
+title: Billing operation status
+openapi: "/openapi/auth-api.json GET /api/v1/auth/billing/operations/{operation_id}"
+description: "Read the status of a billing operation. Readable with an API key."
+---
+
+import PaidPricingStatus from '/snippets/paid-pricing.mdx';
+
+<PaidPricingStatus />
+
+<Note>
+Readable with an API key, so scripts and `rig limits` / `rig whoami` can show billing state. See [pricing and billing](/concepts/pricing-and-billing#integration-and-retry-behavior).
+</Note>
+
+Read an operation owned by the authenticated account. Operations may be creating, pending_payment, pending_period_end, applied, expired, or failed. Verify the server-confirmed operation and relevant subscription or wallet projection; a browser marker is not a financial receipt. The generated response schema is generic JSON.
+
+Account billing requires an authenticated account identity with appropriate billing permissions. Workspace bridge identity is not an account billing credential. See [managed wallet](/ai/managed-wallet) for the financial contract.