jona62 · Oct 5, 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,33 @@ 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-v1 draft
+
+Paid-v1 pricing, pooling, and wallet pages are upcoming documentation, with rollout
+status in `verification/paid-pricing.mdx` and source provenance in
+`verification/paid-pricing.json`. This draft is not publication or production
+rollout evidence. Historical v0.13 verification remains unchanged.
+
+`verification/paid-v1-schemas.json` contains selected server-export components,
+not hand-authored contracts. `scripts/sync-paid-schemas.py` copies only those
+wallet and limits components into the existing gateway spec, preserving unrelated
+paths and schemas. The auth spec is the complete pure auth-service library export,
+verified against its recorded SHA256. Verify with `--check`. To compare a later
+gateway export:
+
+```bash
+python3 scripts/sync-paid-schemas.py --source /path/to/final-openapi.json --check
+```
+
+Both current exports use exact Rust 1.93.1 at primary revision
+`652120cb2273c0383158cdd15136542ab59b74f1`. The gateway has an offline
+`--print-openapi` branch; the auth export uses its pure `rig_auth::openapi()`
+library function without invoking auth-service startup. If the primary head
+changes, regenerate both sources, replace the recorded bundle/auth export and
+provenance, and revalidate against final hosted CI before publishing. Several
+billing responses remain generic JSON schemas in the server source. A production sync from older
+binaries can reintroduce obsolete monthly wallet promises: run the paid-schema
+check and review the sync diff before accepting it. Do not mark paid-v1 current
+until the deployed catalog, migration, financial and Linux runtime release gates
+are confirmed.
diff --git a/ai/managed-wallet.mdx b/ai/managed-wallet.mdx
@@ -0,0 +1,83 @@
+---
+title: Managed AI wallet
+description: Upcoming paid-v1 balance, durable reservations, exact charges, and verified renewal behavior.
+---
+
+<Warning>
+This is the upcoming **paid-v1** wallet contract, pending rollout and final API synchronization. Check [pricing and billing](/concepts/pricing-and-billing) and your account's confirmed Billing state before purchasing or integrating.
+</Warning>
+
+Managed AI uses an account wallet shared by your workspaces. New paid compute tiers include no AI grant. **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-v1 new tiers receive no included AI. 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.
 
+Upcoming [paid-v1 compute plans](/concepts/pricing-and-billing) include no AI grant. 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,7 @@ 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)."
 ---
+
+<Warning>
+The staged schema describes upcoming paid-v1 wallet semantics: `remaining` is available funds and `total` is balance before holds, not a monthly grant. Final server-artifact synchronization and rollout verification remain pending. See [managed wallet](/ai/managed-wallet) and [rollout status](/verification/paid-pricing).
+</Warning>
diff --git a/api-reference/ai/get-limits.mdx b/api-reference/ai/get-limits.mdx
@@ -3,3 +3,7 @@ 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.
 ---
+
+<Warning>
+The staged schema includes upcoming paid-v1 entitlement and sustained account CPU fields. These are draft contracts pending final source synchronization and rollout. Current account responses remain authoritative; see [resource limits](/concepts/limits) and [rollout status](/verification/paid-pricing).
+</Warning>
diff --git a/api-reference/billing/catalog.mdx b/api-reference/billing/catalog.mdx
@@ -0,0 +1,13 @@
+---
+title: Billing catalog
+openapi: "/openapi/auth-api.json GET /api/v1/auth/billing/catalog"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+Inspect the upcoming paid-v1 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,13 @@
+---
+title: Change plan or add-ons
+openapi: "/openapi/auth-api.json POST /api/v1/auth/billing/change"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+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,13 @@
+---
+title: Create subscription checkout
+openapi: "/openapi/auth-api.json POST /api/v1/auth/create-checkout-session"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+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,13 @@
+---
+title: Create billing portal session
+openapi: "/openapi/auth-api.json POST /api/v1/auth/create-portal-session"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+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,13 @@
+---
+title: Create credit-pack checkout
+openapi: "/openapi/auth-api.json POST /api/v1/auth/billing/credit-packs/checkout"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+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,13 @@
+---
+title: Billing operation status
+openapi: "/openapi/auth-api.json GET /api/v1/auth/billing/operations/{operation_id}"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+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.
diff --git a/api-reference/billing/subscription-status.mdx b/api-reference/billing/subscription-status.mdx
@@ -0,0 +1,13 @@
+---
+title: Subscription status
+openapi: "/openapi/auth-api.json GET /api/v1/auth/subscription-status"
+description: "Upcoming paid-v1 account billing operation, pending rollout."
+---
+
+<Warning>
+This is a draft paid-v1 reference generated from the auth service at the recorded source revision. It does not confirm live rollout. See [pricing and billing](/concepts/pricing-and-billing) and [source verification](/verification/paid-pricing).
+</Warning>
+
+Read the confirmed plan, paid-through deadline, transition deadline, pending change, add-ons, and wallet projection. A pending plan or browser checkout success does not increase confirmed quota. Compute authorization comes from the limits projection, not a status label alone. 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.