Plan & Usage (your plan, your allowance, your credit)
The one customer-facing money screen: the plan you are on and this month's AI allowance, your prepaid credit balance with a top-up button, a Free versus Pro comparison, and the option to bring your own API key. Card payments happen on the payment provider's own page, opened in a secure window inside the app, and a plan is granted by a verified webhook rather than by the window returning.
On this page
What it is
Settings → Accounts & AI → Plan & Usage. The ONE customer-facing money screen, organized by what a user actually does: see the plan they're on and this month's AI allowance, see and top up their prepaid credit balance, compare Free vs Pro and upgrade or manage ($20/mo Pro via Stripe), and bring their own API key. (A per-seat Team card exists but is held dark until the gateway's Team price is wired — see below.)
Renamed from "Plan & Billing" and expanded on 2026-08-18: it absorbed the credit balance + Buy-Credit (previously buried under Settings → API Keys) and replaced the separate mock Pricing screen, so there is now exactly ONE place to pay. Subscriptions and one-off credit top-ups are still separate money paths with separate Stripe webhooks that never cross — see stripe-credit-topups.md for the credit path.
Where to find it
Settings → Accounts & AI → Plan & Usage. It is the only storefront in the app; the upgrade prompt a free user meets routes here.
How it behaves
What the user sees
- Your plan — the current tier (Free / Pro / a comped tier), read from their Global Auth claim. A lapsed sign-in refresh does not drop the plan to Free: the last confirmed plan keeps applying locally while Omniscio asks the person to sign in again, and the first successful reconnection renews the sign-in silently. Cloud features still need a confirmed sign-in, and the server remains the authoritative check on paid services.
- Monthly allowance meter — how much of the month's pooled-AI allowance is used, and when it resets (first instant of the next UTC month). Fetched on open only, never polled (cost). If the tier has no configured cap the meter hides and says the allowance isn't set up yet; at/over a real cap it clamps to 100% rather than showing a nonsense number. As of 2026-08-25 the per-plan pooled-AI allowance is $0 on every tier — there is no free company-funded AI budget on any plan: general in-app AI declines and falls back to the user's own key / prepaid credit. With a $0 allowance the meter hides entirely and simply says AI runs on your own key or prepaid credit — a zero allowance is not an exhausted one, so there is no bar and no warning. (Until 2026-09-03 this rendered a maxed-out 100% bar and told everyone — paying Pro and Team subscribers included — that they had used up an allowance they never had.) When a real positive cap IS configured and genuinely runs out, the warning is tier-aware: only a Free user is pointed at Pro; a paid subscriber is pointed at prepaid credit or their own key. Two safety-net features (the inbound-email security screen + the Ask-Omniscio keyless help) still run on the shared company pool, exempted from the per-user cap in the gateway — everything else is user-paid. This screen is also where the "built-in AI helpers stopped" inbox card sends the user — it is the one place that answers both halves of that card (how much you get + how to keep going, whether by upgrading or pasting your own key). See built-in-ai-helpers.md for the per-tier numbers and the two card variants. the one place that answers what that card leaves open (how to keep going, whether by upgrading or pasting your own key). See built-in-ai-helpers.md for the two card variants.
- Credit balance + Buy Credit — the prepaid gateway credit, shown right under the allowance so
"what's left" (this month's allowance AND your credit) sits in one place. Top up with a card via
Stripe ($10 / $25 / $50 / $100 presets, or a custom $5–$1,000). The same balance still appears
under Settings → API Keys (creating a pooled key needs it), now with a link back here to add credit.
The balance + Buy-Credit UI is one shared component so both screens stay identical.
The balance can read negative, and it is shown that way on purpose (e.g.
-$0.50) with the note "from usage overage — your next top-up covers it". A charge is reserved as an estimate and settled at the real cost, so a balance can dip slightly below zero; it is small, bounded, and the next top-up absorbs it. (Until 2026-09-03 a negative balance displayed as$0.00— a real debt hidden behind a reassuring zero.) - One Add-credit action from every refusal — wherever the app refuses an AI action because the
prepaid balance is empty (the image studio, Settings, the sidebar and the cloud-session launch
gate), the refusal now carries the SAME Add-credit button instead of a sentence pointing you at a
screen to find yourself. The button opens this screen's top-up through one helper
(
src/renderer/src/lib/open-add-credit.ts), so a surface cannot drift into its own wording or its own destination. Every Add-credit action exists only while the Buy Credit card does. One predicate (src/shared/billing/buy-credit-offer.ts, read through thestripe-credit-topupsflag) decides whether this install offers card payments, and both sides obey it: the renderer helper (the image studio's error tile and toast, the My API Keys balance note), and the main-side producers (a spawn refusal'ssettingLink, an aside refusal'sactionUrl, the Ask Omniscio credits-lane row, the AI-extras credits alert). With Buy Credit off, those surfaces show no button rather than one that lands on a card that is not rendered. On Plan & Usage itself a $0 balance never grows an Add-credit button: the Buy card there IS the destination. The AI-extras credits alert says both ways back on — add credit in Settings → Plan & Usage, or add an API key of your own in Settings → Accounts — so its body agrees with the Add-credit button it shows, instead of naming only the own-key remedy. - Free vs Pro — a plain comparison so the upgrade decision needs no docs. Free's figures are read from the published limits, and Pro lists only the caps it actually lifts and the features the entitlement table actually holds back from Free (recipes, custom share links, and cloud transcription for dictation and plugins — screen-recording captions are not held back, they draw on the monthly speech minutes) — never an AI allowance, because no plan includes one. The refund policy is linked right here on the money screen, next to Manage/cancel.
- Upgrade to Pro — visible only when the user is signed in AND on Free. A paid or comped tier hides it, so nobody is ever invited to buy something they already have.
- Team (per-seat) card — hidden by default. It shows a seat picker and a live $25/seat total,
but the gateway has no Team price wired yet, so an "Upgrade to Team" click would fail with "not
available". Since 2026-09-03 the card sits behind its own in-development flag
(
team-subscription) and is revealed as part of Team go-live, together with the gateway price — never before it. Since 2026-10-18 it is also ANDed with what the gateway reports it can actually charge (plans.teamon the usage read), so the flag alone can never put a price on screen. A storefront that cannot take the money does not show the price. - Manage or cancel subscription — visible only to an actual Pro/Team subscriber. Opens the
Stripe Billing Portal where they can cancel, update their card, or view invoices. A Free user
has nothing to manage, so they never see it.
- The portal does not accept refund requests. Stripe's Customer Portal exposes no refund-request action; what it can show is a link to the refund policy, and only if that is configured owner-side in the Stripe dashboard's Customer Portal settings. Refund requests go to legal@omniscio.com per the published Refund & Cancellation Policy. Do not tell a customer to request a refund in the portal — there is nothing there to click.
- Bring your own API key (BYOK) — use a personal provider key instead of the pooled allowance.
How the upgrade actually works
- The button calls the gateway (
POST /v1/subscription/checkout) and opens the returned Stripe hosted Checkout URL in a dedicated window inside the app (see "Paying inside the app" below). Card details never enter Omniscio. - The gateway pins
client_reference_idto the verified Firebase uid server-side — never a value the client supplies. This is the load-bearing security property: the webhook trusts that field to decide whose account gets Pro, so a client-settable value would let a signature-valid checkout name any victim. - A separate Firebase webhook (
stripeSubscriptionWebhook) receives the verified Stripe event and flips the user'stierclaimfree → pro. Cancel or lapse flips it back. - The tier claim is what the gateway reads to grant the larger pooled-AI monthly allowance.
Because the grant happens on a verified webhook and not on the window returning, closing the window or a flaky network can't leave someone paid-but-not-upgraded. The subscription checkout also returns the buyer to its own confirmation page, which says the plan is active — the prepaid-credit page is only for top-ups, and telling a new subscriber their credit was added would be false.
Paying inside the app (2026-10-18)
Checkout, Buy credit and Manage billing all open a dedicated secure window inside Omniscio instead of the user's web browser. The window has context isolation on, Node off, the sandbox on, no preload script, and its own throwaway session partition, so it holds nothing of the app's and leaves nothing behind. It may only load Stripe's own hosts and the gateway's four return pages — recognised by the exact public origin the gateway reports it built its success and cancel URLs from, never by a host pattern; every other link goes to the normal browser, and popups are refused. No Stripe key of any kind ever reaches that window — it is handed nothing but the hosted URL the gateway already minted for the verified caller.
That origin travels in the same reply as the payment URL. If a reply carries no usable https
origin, the app does not open its own window at all and uses the normal browser instead: a payment
window is never opened where the app could not recognise its own return page.
When the window reaches the success or cancel page it closes itself and the app re-reads the plan without being asked: a short "Confirming your payment…" state runs while a forced, server-verified plan read is polled (a few seconds at first, then more slowly, for up to 45 seconds). On a change the new plan appears where it was, with no Refresh click. If the webhook is slower than that, the screen says so plainly and the plan still arrives on its own — the message never claims a payment failed, because it may simply still be settling.
The user's normal browser is still used when that window cannot be created or loaded, so a payment is never a dead end.
Dismissing the window is never silent (T-27). A checkout that is cancelled or simply closed without paying used to end the purchase with no word at all, so the buyer could not tell whether they had just been charged. The Buy Credit card now answers both: cancelled says "Checkout cancelled. Nothing was charged.", and closed says "Checkout closed. If you finished paying, your credit will appear in a moment." The second deliberately never claims nothing was charged — a payment can still be settling at Stripe when the window goes away. Each dismissed checkout is answered once: the credit card owns the credit outcome and the plan screen stays out of it, so the buyer gets one message.
When the server is not fully configured (2026-10-18)
The gateway and the Firebase functions each check their own Stripe settings at startup: the Pro monthly and annual price ids (both sold), and the two webhook signing secrets. A missing setting on a partially configured deploy is reported as an alert that names the setting — never its value — and a deploy with no Stripe settings at all is the deliberate off state and stays quiet.
Two safety properties ride on that check. A storefront offer is only ever shown when the gateway reports it can charge for it. And a Stripe webhook on a deploy holding exactly one of its two secrets now answers 503 instead of a 200 acknowledgement: Stripe treats a 2xx as delivered and never retries, so a 200 there would lose the payment for good, while a 5xx keeps the event in the retry window until the secret is fixed.
Monthly or annual (2026-09-08)
Pro is sold on two intervals, which is what the Terms advertise: $20/month, or $192/year — about 20% off. The Pro card carries a Monthly / Yearly toggle and shows the saving next to it.
A few things that are true and non-obvious:
- The screen never states the discount as a fixed number. It divides the two prices and rounds. If Pro is ever repriced, the percentage moves with it instead of quietly contradicting the Terms, and a build-failing guard reads the published Terms document and turns red if the code and the legal text ever disagree.
- The choice only appears once the annual price is actually live — the
pro-annual-billingflag AND the gateway reporting that its annual price is configured (plans.proAnnualon the usage read). Before that the card is monthly-only, because a priced offer nobody can buy is worse than no offer at all. A missing answer (an older gateway, or a failed read) hides the choice. - The interval you pick is what the gateway charges against. It is validated on the way through; an unrecognised value is rejected rather than quietly billed as monthly. It changes what is billed, never who — the account charged is always the verified signed-in user.
- Both Pro prices grant the same Pro. The webhook maps the monthly and the annual price id to the same tier, so an annual buyer is entitled exactly like a monthly one.
The annual renewal reminder (2026-09-08)
The Terms promise: "For any annual (one-year) plan, we will send a renewal reminder before the renewal charge." A daily job does this.
- It emails an annual subscriber 30 days before the charge, once per period.
- It never emails after the charge has happened — a notice that arrives afterwards is not a reminder, so a renewal date already in the past is out of range by construction.
- It skips anyone who is already cancelling (nothing renews), anyone on monthly (the promise is annual-only), and anyone whose payment is retrying after a failure (that is dunning, not a clean renewal — telling them "you will be charged on the 14th" would be wrong).
- It sends first and records second, deliberately. If recording fails, the worst case is a duplicate reminder next day; the alternative failure — marking someone as reminded when the email never went — would breach a published promise silently.
- Every run logs what it scanned, sent and skipped, so a quiet month and a broken job do not look identical.
- It reads the renewal date the Stripe webhook records on each subscription event. The daily Stripe reconciliation also fills in a date that is missing, so a subscriber the webhook missed is not skipped silently; it never overwrites a date that is already there.
- Its cancel instruction names the path the product actually has. The letter tells an annual
subscriber to cancel from Settings → Plan & Usage → Manage or cancel subscription — the same
path Terms §5.5 and EULA §5(f) publish, and the same label the Settings nav renders
(
Settings-section-groups-new-layout.tsx). The screen kept itsplan-billingid when its label changed to "Plan & Usage" on 2026-08-18, and the letter went on naming the retired label, so a customer who followed it found no such section.tests/unit/firebase/renewal-reminder-email-cancel-path.test.tsfails if the letter names the old one, so a future rename has to move the label, the Terms and this letter together.
How manage / cancel works (2026-08-17)
The Manage or cancel subscription button calls the gateway (POST /v1/billing-portal) and opens
the returned Stripe Billing Portal URL in the same secure in-app window checkout uses. Same
load-bearing security property as
checkout: the gateway resolves the Stripe customer SERVER-SIDE from the verified Firebase uid's
users/{uid}.stripeCustomerId — never a value the client supplies — so a signed-in user can only
ever open their own portal. Cancelling flows back through the same verified stripeSubscriptionWebhook
that a subscribe does (it flips the tier), so the button never changes the plan itself. The refund
terms (14-day, less consumed AI credits) live in the public
Refund & Cancellation Policy. The portal is where a customer
cancels, updates a card, and pulls invoices — it does not accept a refund request (Stripe's
Customer Portal has no such action); the policy routes those to legal@omniscio.com.
Go-live state (2026-10-26): activated. Stripe's Customer Portal is live in BOTH modes — test
(bpc_1UUfmiGal0UC1UHmrc6raGl0) and live (bpc_1UUfylBDtMuC4WPfq4jPe4Xi) — with cancel at period
end, card update and invoice history enabled and plan switching off, so a customer can cancel,
replace a card and download invoices but cannot move themselves between plans. The gateway creates
each session with no configuration id, so whichever configuration is the DEFAULT for that Stripe
mode is the one customers see: what the portal offers is a Stripe-dashboard setting, not a deploy.
POST /v1/billing-portal still answers 503 when Stripe itself rejects the call (an outage, or a
customer deleted on Stripe's side), and the button turns that into a friendly "not available" rather
than a dead action.
Deleting your account also cancels the subscription (2026-10-11)
The Terms already said so — "Deleting your account cancels any active subscription" — and until this date the product did not do it. Account deletion erased the Firestore, Auth, storage, saas-api and Forms rows and never told Stripe anything, so the plan kept renewing and the customer kept being charged for an account nobody could sign in to. The webhooks that would normally notice resolved no account and answered a quiet "unknown customer", which looked exactly like health.
Deletion now ends the billing as part of the same erasure. Which way it ends follows the published cancellation promise rather than an internal preference:
- A plan with a paid period running (an active subscription, or a trial that has not converted) is set to end at that period. Nothing renews, and a trialist who deletes is never charged at all.
- Anything else still live — a failed renewal, an unfinished signup, a paused plan — is cancelled straight away, so a dunning retry cannot turn into a charge for a closed account.
The delete dialog now says this out loud, which it previously did not: it promised only that billing history is kept, leaving a subscriber to guess whether they would be charged again.
If Stripe cannot be reached the deletion still goes through — the account's data is gone either way — and the cancellation is retried automatically until it succeeds. Two things stay open, and are worth knowing rather than discovering: accounts deleted before this shipped keep being charged, because there is no longer any record linking them to their Stripe customer; and a previous subscription from an earlier signup can only be found if the account recorded that customer, which the returning signup now does going forward.
A full refund also cancels the subscription (2026-10-27)
A full refund of a subscription charge used to return the money and drop the customer to Free while the Stripe subscription stayed alive, so the next period billed someone who had already been refunded. The refund branch of the subscription webhook now cancels the subscription as well, immediately and with no proration invoice.
- The subscription is read from the refunded charge's own invoice, never from the customer's current subscription, so a refund of an old charge can only cancel the subscription that charge paid for.
- The invoice is found from the charge even when the webhook event carries no
charge.invoice: thebasilAPI release removed that field, and a payload is rendered at whatever version the Stripe endpoint is set to, which this code cannot see. When the field is absent the webhook asks Stripe's invoice-payment list which invoice that charge paid — the documented replacement — so a basil endpoint cannot turn every subscription refund into a silent "credit top-up" no-op. - Every subscription invoice refunded in full cancels, whatever it paid for. That includes a
mid-term upgrade or seat change (
billing_reason subscription_update), which until 2026-11-08 cancelled nothing and left a refunded customer billing. To correct a seat count without ending the plan, refund part of the charge instead: a partial refund changes nothing. - The tier revocation runs first and stands on its own: if Stripe cannot be reached, the customer is still off the paid plan, the webhook answers 500 so Stripe retries, and the money-lane alert fires. A refunded customer never keeps paid access while a cancellation is outstanding.
- A partial refund, a refund of a credit top-up, and an invoice that carries no subscription change nothing.
- A redelivery, or a subscription somebody already cancelled by hand, answers
already-canceled: a quiet 200, never an error and never a second cancellation. - It needs the Stripe API key bound to the webhook deploy (
gateway-stripe-secret, the same secret the daily reconciliation sweep uses). Without it, a full refund answers 500 and keeps retrying rather than silently leaving the subscription alive. - The refund may be issued from the Stripe dashboard or from our own tooling; handling it at the webhook covers both.
The published Refund & Cancellation Policy §3/§4, the Terms §5.5/§5.6 and the EULA §10 now say the same thing: a full refund ends that paid period and cancels the subscription, so it will not renew. The daily sweep's refund guard (a repair never raises a refunded account back to a paid tier) is unchanged and remains the net for a webhook that never arrives.
Buying credit before the balance has loaded (2026-10-28)
If the balance had failed to load when you clicked Buy, the purchase used to finish on Stripe but the card never confirmed it: it waited the full 45 seconds and showed "Still confirming". The card now reads your balance once more just before checkout opens and compares against that, so a purchase confirms as soon as the credit lands — even when the credit arrives before the payment page returns. If the balance still cannot be read, the card simply refreshes it when you come back instead of starting a confirmation it can never finish.
The renewal date on your plan (2026-10-28)
Plan & Usage now shows when a subscription renews — or, if you cancelled, when it ends. The date was always being recorded each time Stripe reported on the subscription, but the app only accepted it in one format and the record stores it in another, so it was silently dropped and the line stayed blank. An unreadable or missing date still shows nothing rather than a wrong one.
Behaviour worth knowing
- A billing route stays open after a downgrade. The primary Manage or cancel subscription button is offered to Pro and Team only, so a user the webhook had just dropped to Free — a failed payment that ended the grace week, or a subscription from an earlier signup — would otherwise lose the only in-app way to cancel, change the card or read an invoice. On Free (or an unrecognised plan) the same screen offers Still being charged? Open the billing portal, which calls the same gateway route and resolves the Stripe customer server-side from the verified uid; it names the support address beside it for the case where nothing is linked to the account. Enterprise (comped, handled by its account team) and a signed-out visitor are not offered it.
- A failed card keeps Pro for exactly one week past the day the payment fell due (
past_due), then the plan drops to Free — a deliberate dunning grace so one expired card doesn't instantly cut off a paying customer, without letting an unpaid account keep a paid plan. The clock runs from the START of the unpaid billing period, not its end: Stripe advances both dates when it issues the renewal invoice, so a period end sits on the far side of the period nobody has paid for. One successful renewal re-grants, so a wrong call heals itself. - A full refund of a subscription charge revokes Pro back to Free. When Stripe reports a
subscription charge fully refunded (
charge.refunded), the webhook downgrades the tier to free, so a refund can't leave someone holding a paid month's AI allowance for free. A partial refund and a one-time credit top-up refund never touch the plan. (Needs the webhook endpoint subscribed tocharge.refunded— see the subscription-tier contract's go-live steps.) - A chargeback does the same, and also cancels the subscription.
charge.dispute.createdon a charge that paid a subscription invoice revokes the tier to free and then cancels the subscription behind that invoice, so a disputed payment never leaves the plan — or the billing — running. A dispute on a credit top-up changes nothing. (Needs the endpoint subscribed tocharge.dispute.created; Stripe's dispute→cancel automation may stay on as a second guard.) - A subscription never overwrites an admin-granted tier. It owns the free↔pro↔team axis
(
ManagedTier = 'free' | 'pro' | 'team'); anenterprisegrant is left alone in both directions. So a Team subscriber's plan IS subscription-managed — onlyenterpriseis admin territory. (The retiredstartertier no longer exists; the ladder is free < pro < team < enterprise.) - If the gateway has no Pro price configured, the button surfaces a friendly "not available" rather than a dead checkout, and credit top-ups keep working untouched.
- An empty balance is never described as a spend. The gateway answers an unfunded call with a
plain
402, andGATEWAY_ERROR_CODEScarries no code that separates "never funded" from "spent" (PAYMENT_REQUIRED,CAPACITY,STARTER_CREDIT_EXHAUSTED— the last only for the one-time starter grant). So every surface that used to say the credits were used up now says the credit balance is empty and names both real fixes — add credit, or move to your own key / own Claude account, whichever that surface can actually use:AI_EXTRAS_CREDITS_EXHAUSTED_MESSAGEand thealert.aiHelpersCreditsExhaustedinbox card (built-in AI helpers),ASK_AMC_CREDITS_EXHAUSTED_MESSAGE(Ask Omniscio),alert.setupReminder.bodyNoCredit(the "Finish setting up" card) and the managed session's turn-end copy.humanizeManagedCreditsExhaustedkeeps "run out" on purpose: the only session that reaches it already ran on credits. The two alert strings are pinned by earlier locale patches, so any rewording has to ship in a branch patch with$supersedes— editing the code default alone never reaches a user. The "Finish setting up" card is the one surface that also checks for PRIOR usage (2026-11-16): a zero balance and a never-funded balance are the same answer here, so it shows that copy only to a user who has run an agent on this install (hasEverUserAgentRun) and otherwise says connect an account — a fresh free-tier account was being told its balance was empty seconds after its first sign-in (detail:.claude/memory/onboarding-post-setup-surfaces.md).
Company-funded AI is a Pro perk (2026-08-15)
The "extra" (non-Claude) AI services that spend Omniscio's OWN keys are Pro-only for signed-in users, except where noted below — voices moved to metering on 2026-09-02 and the API-key gateway opened in August. Free and anonymous users always keep their own-key (BYOK) and free on-device options:
- Gated now: GLM company credits and cloud speech-to-text.
- Metered, not gated (2026-09-02): company read-aloud/narration voices (Fish + Soniox) are
no longer Pro-only. Any signed-in user can use them; each synthesis spends their plan's monthly
voice time first, then their prepaid credit, and only a user with neither is stopped — with a
top-up/upgrade prompt, never a message about an API key they never entered. Included voice time
per month: Free $0 · Pro ~$3.75 (about 5 hours) · Team & Enterprise ~$7.50 per seat (about 10
hours). A free account therefore runs entirely on credit. Bringing your own voice key removes
the metering altogether. Voice has its own budget line, deliberately separate from the
company-AI allowance below, which stays
$0on every plan. - Open to any signed-in user (2026-08-24): the API-key credits gateway — minting + using a
personal
jls_sk_key. The Pro paywall on minting was removed for adoption; spend is still prepaid-gated (a$0balance blocks minting + declines calls, fail-closed). The managed proxy lanes CrofAI / DeepInfra / GLM keep their own Pro gate; DeepSeek was opened to all signed-in users too (2026-08-25), so free users with credit can call it as well. OpenRouter company-credit sessions — running any model OpenRouter serves (~400) on the company key — are likewise open to any signed-in user with credit (2026-08-27), priced live at the standard 10% markup. - Still free for everyone: bringing your own voice/provider key, and on-device voice (local Whisper) — never gated.
- Wired but open: the inbound-email safety pre-screen and the in-app help fallback are Pro-capable but left ON for everyone today (flippable later, no redeploy).
- Reach: applies to signed-in users on the multi-user/cloud deployment; a plain single-user install runs as the operator and keeps everything (the operator is never restricted on their own machine). That "keeps everything" is a DESKTOP promise only. A service running on Omniscio's servers — a relay, the credits gateway — sees a plan, not an operator, so it cannot honour it. Where a surface has a server-side check, the server decides. This bit a real user on 2026-09-02: a single-user install was told locally that company voices were allowed, the server refused for not being Pro, and the app relayed that as "check your Fish Audio API key" — for a key they had never entered. Voice now meters instead, so it needs no operator exception at all.
A free signed-in user who hits one of these sees an Upgrade to Pro prompt instead of a dead
button. Enforced app-side + (for GLM) server-side; the remaining server-side backstops are a tracked
follow-up. Detail: .claude/memory/contracts/company-funded-ai-paywall-contract.md.
Plan limits in practice: projects
The money screen's Free vs Pro card quotes the number of projects each plan allows, and that is the cap most people meet first. The rules, precisely:
- Free allows 8 projects. Every paid tier (Pro, Team, Enterprise) is unlimited — the cap is lifted entirely rather than raised.
- Only real projects count. A project counts when it is one you created, pointing at a folder on
disk. The rows Omniscio seeds for you are excluded: the built-in hubs (Gmail, Daily Digest, plugin
sentinels) and the agent home folders (
~/Claude,~/Codex,~/Gemini). A project you deleted or archived stops counting. Re-adding a folder you already have open never counts as a new project — Omniscio answers "a project already exists for this folder" instead. - The cap is on by default. It applies to a signed-in Free user. Someone who is not signed in, and a single-user / operator install, is never limited.
- Projects you already have keep working. If you are already past 8, nothing is removed or locked; only adding one more is refused until you upgrade or remove a project.
- What you see at the cap. Adding a project past the limit is refused with "You've reached your plan's project limit. Upgrade to add more projects." Nothing is lost or half-created. The project count shown in the app comes from the same check, so it never says there is room when there is not.
- Where the fix lives. The refusal is a signpost, not a dead end: Settings → Accounts & AI → Plan & Usage is the one storefront, and the Upgrade to Pro button on it lifts the cap immediately. A single-user / operator install is never limited.
The count is enforced in the main process when a project row is created, so it applies identically from the app, the phone, and the CLI — it is a plan limit, not a UI guard.
Plan limits in practice: everything else
The Free plan has more limits than projects. They are all switched off today and turn on only when Omniscio flips them on, so nothing below happens to anyone yet. Someone who is not signed in, and a single-user / operator install, is never limited.
| Limit | Free | Pro | What you see at the limit |
|---|---|---|---|
| Active tasks | 100 | unlimited | "You've reached your plan's limit of active tasks — upgrade for more." Done tasks do not count. Copying a task counts every task it copies. |
| Mind maps, flowcharts, task lists | 10 each | unlimited | The same upgrade message, naming the thing. |
| Agent emails | 500 a month | 3,000 a month | "Your agent has hit your plan's monthly email limit." Emails your agents send to your own address never count. |
| "Sent by Omniscio" line on agent emails | yes | no | Added at the bottom of each email, except ones to your own address. |
| Team Chat workspaces you own | 1 | 5 | "You've reached your plan's Team Chat workspace limit." |
| Channels per workspace | 10 | 50 | "You've reached your plan's Team Chat channel limit." |
| Guests per workspace | 3 | 15 | Invitations still waiting to be accepted count too. |
| Team Chat message history | 90 days | 365 days | Older messages are deleted once a day. |
| Team Chat file storage | 5 GB | 50 GB | An upload that would go over is removed. |
| Cloud backup history | 90 days | 365 days | The copy saved to the Omniscio cloud leaves out messages from sessions older than this. |
What is never touched. The history on your own computer is never trimmed on any plan, and neither is a backup you save to your own folder (Dropbox, OneDrive and so on) or a local export. Only the Omniscio cloud copy and Team Chat, which lives in the cloud, follow these windows. Session titles and spend are kept in the cloud copy even when their messages are left out.
Limits on every plan. A workspace can hold at most 200 channels and 50 guests on any plan. These are safety limits against runaway use and are always on.
Moving to Free keeps what you have. Nothing you already created is removed when a limit turns on; you just cannot add more past the limit. The exceptions are the two history windows and the file cap, which apply to everything in Team Chat once they are on.
Free credits for saving a card — optional, off until switched on (2026-11-04)
An optional offer: an account that saves a card with Stripe gets a one-time grant of free credits in its Credit balance. Saving a card is never required for anything — the owner's rule is that no user ever has to add a card — and while the offer is off nothing about it shows anywhere.
- What the user sees (only while it is on): a "Get $X in free credits" card in Plan & Usage, right under the current plan, with an Add card button. It opens Stripe's save-a-card page (no charge) in the same in-app window auto top-up uses; on return the credits appear in the balance. The card disappears once the account has claimed it.
- Once per account and once per card. The same card cannot fund a second account, an account cannot claim twice, prepaid cards are refused, and a card saved on another account's page never counts.
- A monthly budget. Grants stop for the rest of the month once the offer's monthly total is spent, so a pile of throwaway cards cannot drain it.
- Not revenue. Grants are kept apart from purchases, so they never show as revenue or as an ad-tracked purchase, and refunds or disputes cannot touch them.
- Turning it on or off: ask any agent ("turn on card credits at $5, $500 a month"). It is one write
to the gateway setting
gateway_config/card_credit_offer—enabled,amountUsd(default $5, at most $100) andmonthlyBudgetUsd(default $500, at most $10,000). It takes effect within a minute, with no deploy. An absent or unreadable setting means off. The offer also needs its own secret,gateway-card-offer-pepper(it keeps cards hashed); without it the offer stays off. Deleting an account removes its claim, but the card stays used. - Contract:
.claude/memory/contracts/card-credit-offer-contract.md.
If checkout won't start
Clicking Upgrade to Pro (or a credit top-up) and getting "We couldn't start checkout. Nothing was charged." means the payment step never opened. Two things are worth knowing:
- Nothing was charged, and no subscription was created. The message says so because it is true: the checkout session is created server-side before the browser opens, and a failure there leaves your plan and your card untouched.
- Try again in a moment. If it keeps failing, the cause is on the payment side rather than yours — a payment provider that is not configured or not reachable answers exactly this way. Email support@omniscio.com; do not retry a card in a loop. The same rule covers the portal: if Manage or cancel subscription reports the portal is not available, nothing about your plan has changed.
"What each plan includes" (audit F065)
The Plan & Usage screen carries a card listing every tier-gated capability, grouped by the plan
label that unlocks it. It is derived at module load from the entitlements table itself
(ALL_CAPABILITIES + minTierLabel + capabilityDescription), never hand-copied — adding,
re-tiering or retiring a capability moves this list in the same commit. It exists because the
comparison cards above only sell caps plus three perks, so "is this a paid feature or a bug?" had no
answer anywhere in the product.
Related
Related — Contract
- Contract:
.claude/memory/contracts/plan-billing-storefront-contract.md - Contract:
.claude/memory/contracts/stripe-subscription-tier-contract.md(the webhook that flips the tier) - stripe-credit-topups.md — the separate one-off credit path
Last verified 2026-11-04