4.1.0
Released
Features
Added
POST /api/billing/change-plan, which upgrades a subscription to a higher plan by charging the new plan in full at once, crediting the unused time on the old one and restarting the billing period and the AI credit month. A declined card changes nothing, and downgrades, cancellations and monthly/annual switches stay in the Billing Portal at period end. No plan above Pro is for sale yet, so the route has nothing to upgrade to until the rollout (#1131)Billing now says when a plan change is waiting for the end of the period — "Changes to Uncommon on 14 December. You keep Epic until then." — for a downgrade or a monthly/annual switch made in the Stripe billing portal, and
/pricingexplains how upgrades and downgrades work once more than one paid plan is for sale (#1131)Achievement badges are drawn from one shared set of rarity colours in both light and dark, on the web and in the app, so a rarity looks the same wherever it appears. A badge's rarity is now shown as a chip with its name and one to five pips in the profile gallery on the web and in the app, named badges carry the pips, and locked badges show them beside the rarity's name, so rarity reads without relying on colour (#1132)
The pricing page becomes a ladder once more than one paid plan is for sale: a card per plan in its rarity, one monthly/annual switch for the whole row with each plan's saving, a comparison table with a column per plan, and buttons that fit the account — subscribe, upgrade now, or switch at the end of the period. A paid plan with no price for the chosen interval offers no way towards buying it, signed in or out. With Free and Pro alone on sale the page is unchanged (#1133)
Billing in Settings follows the pricing ladder once more than one paid plan is for sale: the plan is shown in its rarity, the usage bar takes the rarity's colour, and the page offers one step up from the current plan — or, on the top plan, simply what it includes. With Free and Pro alone on sale the page is unchanged (#1134)
A locked AI model in the model picker now names the plan that unlocks it. Once more than one paid plan is for sale it wears that plan's rarity badge ("Epic and above") and its upgrade link opens the pricing page at that plan's card (#1134)
Once more than one paid plan is for sale, running out of AI credits or daily AI actions offers the next plan up, linked to its card on the pricing page. The notice can be dismissed and comes back only the next time the account runs out; on the top plan it offers nothing. The message shown at the daily limit names that same plan (#1134)
Once more than one paid plan is for sale, your own profile header and the Billing entry in Settings show your plan as its rarity badge. It appears only on your own pages, never on anything other people see (#1134)
Admin covers the whole plan ladder: the Users list filters by any of the five plans and shows each account's plan as its rarity badge, and a model persona can require any plan, chosen from a list that names who each one lets in ("Epic and above") and filtered the same way (#1135)
Admin has a read-only Plans page: every plan in the catalogue with its allowance and whether it is for sale, beside the Stripe price its checkout charges for each interval, flagging a plan that is for sale with a price missing (#1135)
Admins can grant an account any plan from the Users list, after a confirmation. A granted plan is kept whatever billing does; choosing Free withdraws the grant and lets the account's subscription decide again. Each change appears in the audit log (#1135)
Admin reports are broken down by plan. AI Spend has a row per plan for the chosen month: accounts, credits spent, estimated AI cost, how much of their allowance the plan's accounts use (median, 90th percentile, highest, and how many reached the limit) and, for the current month, an estimate of what the plan's active subscriptions bring in at list price. Analytics lists all five plans in ladder order, shows paying accounts per plan across the chosen range, and counts new subscriptions, upgrades, downgrades and cancellations; these start from the day plan history began. The dashboard's Total Users tile says how many are paying and how many were granted a plan (#1135)
The mobile app understands the plan ladder. Its Billing screen draws a plan outside Free and Pro in its rarity, with what is left of the period's AI credits and what that plan includes, and switches every plan to that layout once more than one paid plan is for sale; it still shows no price, no purchase button and no link. The app now reads the plan catalogue, so an account on a plan newer than the installed build is named by its plan and offered the models and features its plan covers instead of being treated as Free. On the ladder the model picker lists the models a plan does not include, each under the badge of the plan that unlocks it (#1136)
Epic and Legendary accounts get five web searches per investigation instead of three. The Investigate dialog and the app's Ask sheet quote the searches and the most a question can cost for the plan of whoever is asking, which on a Party Quest is the member, not the owner (#1139)
Legendary accounts can run quests and investigations on Claude Fable 5.2 and GPT Astra, Anthropic's and OpenAI's most capable models, at 7 credits an action. When one fails, the answer falls back to the same provider's next model down first — Fable to Opus, Astra to Terra then Luna — in the worker and in the web app's Quest Coach and Year Theme slate; every other model still tries another provider first. While the pricing page sells only Free and Pro, the web model picker leaves out a model whose plan is not on sale instead of offering an upgrade nobody can buy, and the admin persona form offers the new Flagship cost band. Structured AI calls (the Quest Coach, a theme slate, a pack draft) on Claude Fable and Claude Mythos offer their output tool without forcing it, since those models refuse a forced tool choice (#1139)
Questions asked by Epic and Legendary accounts go first in line when investigations are waiting to be answered (#1139)
Fixes
The pricing page and Billing no longer describe Pro's allowance as "around 100 Claude Opus actions", which real usage did not bear out for investigations. It now reads "400 AI credits a month — around 60 Sonnet investigations or 200 shorter actions", worked out from what investigations have actually cost (#1133)
The banner on Billing after a payment now waits for the plan that was bought and names it. It used to treat any plan at or above Pro as done, so an upgrade from Pro would have shown the old plan as a success without checking again, and a plan below Pro would never have been seen to arrive (#1133)
An account granted a plan other than Pro without a subscription is now told the plan it was actually granted (#1134)
The monthly/annual choice on the pricing ladder no longer outlives the prices it was made for: if the page refreshes to prices that lack the chosen interval, the cards fall back to one that is offered instead of reading as unavailable (#1134)
The message shown when a chosen AI model is above the account's plan names the plan that model actually needs, instead of always saying Pro (#1134)
An account whose plan an administrator granted can no longer buy or upgrade to a plan above it. Billing never moves a granted plan, so such a purchase was charged and changed nothing; the pricing page and Billing now say the grant must be withdrawn first, and checkout and the upgrade route refuse it before Stripe is asked (#1137)
A subscriber left on a re-priced plan's old price can upgrade again. That price no longer names a plan, so the upgrade used to answer that it could not tell which plan the account was on; it now uses the plan recorded for that subscription on that price, as the database already does (#1137)
Technical changes· 35 entries for database, tooling, CI, tests and docs
Database
Added the plan catalogue in
20270101120000_plan_catalogue.sql:plansholds the five-plan ladder agreed indocs/pricing.md(free,uncommon,pro,epic,legendary, with a rank, a rarity, the monthly AI credit allowance, the daily cap, the web searches an investigation may run and whether the plan is for sale) andplan_capabilitiesnames the lowest plan that may use a gated feature.profiles.plan_tierandmodel_personas.required_tierbecame foreign keys toplansin place of theirin ('free', 'pro')CHECKs,plan_creditswas dropped andai_credits_allowance_for()andfree_tier_daily_action_limit_for()readplans.plan_tier_rank()reads the table, and the newplan_tier_covers()andplan_has_capability()are the only comparisons: the Chronicle narration queue, the weekly AI review, the Year Theme alignment check,set_user_plan_tier(),admin_list_users()and the administrative-grant rule inapply_subscription_state()were restated to use them, because each testedplan_tier = 'pro'and would have treated an account on a higher plan as free. Free and Pro accounts keep their rank order, allowance, daily cap and features, andfreeandprokeep their keys. Narration opens from Uncommon, which nobody can reach yet: the three new plans are not for sale, no Stripe price exists for them, and a subscription still grantsproorfree. No persona's plan moved: the ladder puts Claude Haiku, GPT Luna and DeepSeek at Uncommon, but the web app, the worker and installed mobile builds rank a persona's plan against two values and would stop offering them to Pro accounts, so that move waits for the rollout (#1137). The investigation hold and the worker do not readinvestigation_searchesyet; that is #1139 (#1128)Recorded the plan a subscription is for in
20270102120000_subscription_plan.sql.subscriptions.plan_keyreferencesplansand isproon every existing row;plan_tier_for_user_subscriptions()now answers the highest-ranked plan among an account's paying subscriptions instead ofprofor any of them, so two subscriptions resolve upward and cancelling the higher drops to the lower; andapply_subscription_state()was recreated with_plan_keyand_plan_resolved, storing no plan — and granting nothing — for a price the webhook could not place, except on a subscription already on a plan at the same price. A call without the new arguments still records Pro, so the migration and the code can deploy in either order. No plan became purchasable and no existing subscriber's plan changed (#1130)Closed the proration loophole on AI credits in
20270103120000_plan_change_credits.sql.subscriptionsgainedcurrent_period_start,credit_anchor_atandcredit_plan_key;apply_subscription_state()takes the period start and the upgrade route's restart stamp, and raises the allowance a subscription carries only on that proof that the running period was charged in full at the new plan, re-anchoring the credit month there; any other upgrade keeps the allowance it had for that period.ai_credits_allowance_for()andai_credit_period_start_for()read the new columns. An account that never changes plan is unaffected (#1131)Added
admin_set_user_plan(): an admin withai_plans.writegrants any plan in the catalogue, the change is written to the audit log in the same transaction, and granting the lowest plan hands the account back to billing (#1135)Started recording plan history in
20270105120000_plan_change_history.sql.plan_changesgets one row each time an account's plan or who set it changes, written by a trigger onprofilesso billing, admin grants and any later writer are all covered; billing's two writes are folded into the one change they are, accounts already on a paid plan got a baseline row, and a deleted account's rows stay as anonymous counts. Four admin-only reports read it and the ledger:admin_plan_history(),admin_plan_change_counts(),ai_spend_by_plan()andadmin_paying_subscriptions()(#1135)An investigation's web searches now come from the asker's plan (
20270106120000_plan_investigation_searches.sql).set_investigation_budget()stampsweb_search_limitfromplans.investigation_searches— three on Uncommon and Rare, five on Epic and Legendary, none on a free persona or DeepSeek — and the hold is priced from that column, so the hold, the worker and the settlement read one number. Rows already queued keep the limit they were held with (#1139)Added Legendary's flagship personas in
20270108120000_flagship_persona.sql: Claude Fable 5.2 (claude-fable, Anthropicclaude-fable-5-2) and GPT Astra (gpt-astra, OpenAIgpt-6-astra).model_personas.costgained a fifth band,flagship, and both rows weigh 7 credits — Astra's US$10 / US$50 per-million-token rate is a $0.069 text action, and Fable's US$8 / US$40 is 1.6× Claude Opus 5's, which weighs 4 — atrequired_tier = 'legendary', so the plan-tier triggers refuse them to every lower plan on a quest and on an investigation.seed.sqlcarries an idempotent copy. No plan above Rare is for sale yet, so only an account an admin grants Legendary can choose them (#1139)Added queue priority for investigations (
20270107120000_investigation_queue_priority.sql). The worker's claim takes a question whose asker's plan holds the newinvestigation_prioritycapability (Epic and above) before other waiting questions, reading the plan when it claims and storing nothing about priority on the row; a question that has waited more than five minutes is first in line too, so priority never holds anyone back indefinitely. The queue's order reads a newtask_investigations.queued_at, and its priority the plan of a newqueued_by_id, both stamped by a trigger on insert and on a return topendingand never set or moved by a client: a client can send anycreated_atand would otherwise skip the line by backdating its question, and a Party Quest member who requeues another member's question now brings their own plan rather than the asker's, matching who the requeue charge bills. A requeued question joins the back of the line (#1139)
Tooling & Configuration
Two billing failures now reach Sentry, each tagged
billing_alertand grouped into one issue per kind, with an issue alert on thewebproject that emails the team: a Stripe subscription on a price that names no plan (charged and granted nothing), and a Stripe webhook event that failed to apply (the route caught it, so it only reached the log) (#1137)Added item rarity to
@questify/design-tokens:RARITIES(common, uncommon, rare, epic, legendary) with an accent, a soft surface, text for that surface and a quiet border for each, in light and dark, declared inpackages/ui/src/styles/globals.cssandapps/mobile/global.cssand exposed to Tailwind asrarity.<name>.RarityBadge,RarityPips,RarityFrameandRarityNamein@questify/ui/components/rarity, andRarityBadge,RarityPipsandRarityFrameinapps/mobile/components/ui/rarity.tsx, are what plans will be shown with; the web's achievement badge and gallery and the app's gallery now use them instead of their own slate, emerald, sky and amber classes. Epic and Legendary frames carry a still glow on the web and nothing animates on either platform, so there is no motion to reduce. Achievements keep four rarities (#1132)Taught the web app, the worker and the mobile app the five-plan ladder.
@questify/core/ai/plan-tiersdeclaresfree,uncommon,pro,epicandlegendarywith their rank, rarity and the capability each gated feature needs, and addsparsePlanTier()(a plan the build does not know is treated as free),isPaidPlan()andplanHasCapability()besidetierCovers(); the worker, which cannot import core, has the same ladder inapps/worker/src/ai/plan-tiers.ts. Every comparison against'pro'was replaced: Billing, the AI usage card and the checkout return on the web, the weekly AI review switch on the web and in the app, the app's read-only plan screen, the worker's choice of model for the Year Theme alignment check, and the worker's investigation fallback, whose two-value rank table read a persona on any other plan as unrankable and dropped it. The admin persona form keeps any plan on the ladder instead of turning everything butfreeintopro. A lint rule in@questify/eslint-confignow refuses a comparison against a paid-plan literal outside tests. Free and Pro keep their names on screen, and an account above Pro still reads Pro's copy, until the surfaces are reworked (#1129)Made Stripe billing plan-aware without selling anything new. A price names its plan by lookup key (
questify_<plan>_<interval>,@questify/core/billing/prices), withSTRIPE_PRICE_PRO_MONTHLY/STRIPE_PRICE_PRO_YEARLYstill placing the existing Pro prices; the webhook passes the plan to the database and logs a subscription whose price names none;POST /api/billing/checkoutaccepts{ plan?, interval }(@questify/core/api/billing,plandefaulting topro) and answers 404 for a plan whoseplans.is_purchasableis false before it looks for a price./pricingand/settings/billingfind their intervals and amounts the same way, so a deployment that names its prices by lookup key alone still shows its buttons.pnpm dev:tui -- stripe --cataloguecreates a sandbox product and monthly and annual price for each paid plan, idempotently (#1130)Moved what each plan includes into
@questify/core/billing/plan-catalogue, keyed by plan for all five: the allowance lines,planFeatureList()andplanComparisonRows(), which take the plans a page lists so a page selling Free and Pro keeps its existing copy. The comparison table takes any set of plans, groups its rows, marks a missing feature "Not included" and scrolls inside its own keyboard-reachable region. Nothing new is listed on/pricingyet (#1133)
Tests
Added the
plan-ladderMaestro flow: an account granted Epic opens You → Billing and then picks a paid model in New Quest. The E2E build now turns onBILLINGandMODEL_PERSONAS(#1136)Added
rarity.test.tsto@questify/design-tokens: each rarity's text meets WCAG AA (4.5:1) on its own surface, on a card and on the page, and its accent 3:1 against all three, in light and dark; every rarity has its own name and pip count; and the list and names matchplan_rarityandplansin20270101120000_plan_catalogue.sql. Component tests cover the badge, pips and frame for all five rarities on the web and in the app (#1132)Held both TypeScript copies of the ladder to
20270101120000_plan_catalogue.sql:plan-tiers.test.tsin@questify/coreand in the worker read the migration's plans and capabilities and fail when a key, rank, rarity or minimum plan differs. Added cases for a plan above Pro, a plan below it and a plan the build does not know to the worker's fallback and alignment tests, the web's Billing, AI usage, checkout return, notification settings and persona form tests, the app's notification settings test and the shared billing copy test; the fallback test includes a persona placed at Uncommon still being offered to a Pro payer, the regression found on #1140 (#1129)Added
supabase/tests/plan_catalogue.sql(41 assertions) for the plan catalogue: the five plans and three capabilities, the foreign keys refusing an unknown plan, rank and both comparisons failing closed for a plan or capability that does not exist, a scan that fails when any function inpubliccompares a plan to a paid-plan literal, the tables being readable signed out and writable by no client, every paid persona still needing Rare, persona access following rank at each plan, and each plan's allowance, daily cap, narration and an administrative grant above Rare surviving a billing event.rls.sqlgained four assertions that a signed-in user cannot write either table,weekly_ai_review.sqltwo that a Legendary account is due its review and an Uncommon one is not, andyear_theme_alignment.sqlone that an Uncommon account's check cannot be charged a paid model (#1128)Added
supabase/tests/subscription_plan.sql(26 assertions): each paid plan granted as bought, the higher of two subscriptions and the fall to the lower, an unplaceable price granting nothing, a moved lookup key not stranding its subscribers, the pre-migration call still granting Pro, an unknown plan refused without recording its event, both delivery guarantees, and the recreated function's single signature and service-role-only grant;rls.sqlgained eight assertions thatplan_keyis owner-read and cannot be written or named by a signed-in or signed-out client. Covered lookup-key parsing, the checkout schema, price resolution, the webhook's plan and the catalogue step in Vitest andnode --test(#1130)Added
supabase/tests/plan_change_credits.sql(25 assertions): a stamped restart earning the full allowance and a fresh credit month, an unstamped upgrade between every pair of plans keeping exactly the lower plan's allowance for its period, a plan that rose together with a new period held because timing is not proof, a stamp for another plan proving nothing, downgrades never held upward, and an administrative grant untouched by a hold.rls.sqlgained eight assertions that the credit state is owner-read, cannot be written by a signed-in or signed-out client, and that the restart proof cannot be supplied from a user session. Covered the upgrade module, the route and the webhook's stamp in Vitest (#1131)Covered the pending-change read and its Billing sentence, the gated pricing answer, and persona fallback after a downgrade at every step of the plan ladder: a quest keeps its stored persona, generates on one the plan covers, and returns to the stored one when the plan covers it again (#1131)
Held every number in the plan copy to the plan catalogue migration and to the measured credit rates: each allowance line's credits, the search counts, and that no line promises more than its credits buy (#1133)
Covered the pricing ladder, the action each plan card offers for every kind of account, the upgrade confirmation, the structured-data offers and both layouts of
/pricing; found and fixed, from a rendered screenshot, hidden table labels that made the page scroll sideways on narrow screens (#1133)Covered Billing on the ladder at the free plan, a middle plan and the top plan, the next-plan card, the usage bar's colours and the unchanged two-plan page (#1134)
Covered the model picker naming each locked model's own plan on and off the ladder, the plan-card links and the refusal copy for every plan (#1134)
Covered the out-of-credits notice on the ladder (offer, top plan, dismissal, return in a new period), the server read behind it, and the daily-limit message for every storefront (#1134)
Covered the plan badge on the profile header and settings navigation, on and off the ladder, with billing off and on failed reads (#1134)
Covered the five-plan filters on the admin Users and Personas lists, the plan badges, the persona plan select, and how a plan the build does not know is shown (#1135)
Covered the admin Plans page: the catalogue read, each Stripe answer (priced, missing, unanswered, not configured), the flags and the read-only view (#1135)
Covered plan grants in the database (who may grant, every plan, the audit entry, a later billing event, withdrawing a grant) and in the admin Users list (#1135)
Documentation
docs/billing.md→ Rolling out the ladder is the runbook for putting the five plans on sale: release the ladder code, the worker and installed apps on it, the alerts live, the test-clock run, Stripe live products and the Pro product renamed Rare, then one release that puts the plans on sale and renames Free and Pro, with the subscriber check before and after and a rollback that strands nobody. There is no storefront flag: the storefront isplans.is_purchasable(#1137)AGENTS.mdanddocs/ai-investigations.mddescribe queue priority: theinvestigation_prioritycapability read at claim time from the plan of whoever queued the row (queued_by_id), the server-stampedqueued_atclock and the five-minute grace, described as "first in line", never a speed guarantee (#1139)Recorded the agreed five-tier subscription ladder in
docs/pricing.md→ "The tier ladder", named as item rarity: Common (today's Free), Uncommon at C$5.99, Rare (today's Pro, unchanged), Epic at C$24.99 and Legendary at C$49.99, with each tier's credit allowance, persona access and capabilities, and the worst-case model cost against net revenue on monthly, annual and international-card terms. The ladder is agreed and nothing is built or priced in Stripe yet. The section also records what production's credit ledger showed on 14 November 2026: one paying account, none near the 400-credit allowance, and metered investigations settling at about 6 credits on Sonnet and 15 on Opus, so "around 100 Claude Opus actions" overstates what 400 credits buys in investigations (#1127)Documented how a Stripe price maps to a plan in
docs/billing.md→ "Prices and plans" and "Status and plan → tier", the dashboard steps for a plan's prices,subscriptions.plan_keyindocs/schema.md, and the checkout payload indocs/api-endpoints.md(#1130)Recorded the plan-change rule and its arithmetic in
docs/pricing.md→ "Changing plans", and how upgrades, the webhook and the portal divide the work indocs/billing.md→ "Changing plans" (#1131)Recorded how a pending change, a downgrade's fallback and the pricing copy work in
docs/billing.md→ "Changing plans", with the Stripe test-clock scenario to run before any plan above Pro is sold (#1131)