@vibes.diy/prompts 14.3.181 → 14.3.186

package/llms/stripe-subscriptions.md

@@ -2,8 +2,8 @@
 
 When someone asks for **recurring money** — a paid newsletter, a members-only
 club, a monthly coaching community, a subscription tier — build it on **Stripe
-Checkout in subscription mode** from `backend.js`, with the secret key the owner
-supplies, and keep the member's access a mirror of what Stripe says about their
+Checkout in subscription mode** from `backend.js`, through `ctx.stripe` on the
+Stripe account the owner connects with **Connect Stripe**, and keep the member's access a mirror of what Stripe says about their
 subscription. This is a `backend.js` feature (see the backend docs for the
 general handler contract) and a sibling of the `stripe` skill, which takes a
 one-time payment; this page is the recipe for money that keeps moving, where the
@@ -19,76 +19,115 @@ ask: "subscription", "subscribe", "monthly", "per month", "yearly", "membership
 fee", "paid tier", "paywall", "recurring". A one-time charge — dues once a year,
 a ticket, a deposit — is the `stripe` skill, not this one.
 
-**One merchant, many members.** Every member pays the owner's Stripe account,
-whose key is on the vibe. A member is a signed-in person whose membership is a
-record between them and the owner, and the members-only content is a channel
-that record grants. An app where each visitor sells their own subscriptions is
-a platform (Stripe Connect) and a different thing — say so and build the
+**One merchant, many members.** Every member pays the Stripe account the owner
+connected. A member is a signed-in person whose membership is a record between
+them and the owner, and the members-only content is a channel that record
+grants. An app where each visitor sells their own subscriptions is a
+marketplace, a bigger thing than this recipe — say so and build the
 one-merchant half.
 
-## 1. The setup items: the owner's Stripe secret key, and the Customer portal
+## 1. The setup items: Connect Stripe, and the Customer portal
 
 The owner sets up Stripe once. The Setup surface the two items land on — the
 owner-only entry in the app's navigation, the verdict from `/setup`, the
 re-read on focus that unlocks the Join buttons in place — is the use-vibe
 docs' *Some apps need setup before they work*; this recipe contributes two
-items to it. The Stripe items are the secret key and the Customer portal: the backend answers missing-key while ctx.secrets.STRIPE_SECRET_KEY is absent, reads whether a portal configuration has been saved, and its steps link Stripe's API keys page and Stripe's Customer portal settings by URL and name STRIPE_SECRET_KEY in so many words.
+items to it. The Stripe items are Connect Stripe and the Customer portal: the backend reads ctx.stripe.status(), reads whether a portal configuration has been saved, and its steps link this vibe's Settings tab, where the owner presses Connect Stripe under Payments, and Stripe's Customer portal settings by URL.
 The steps are written for someone who has never opened Stripe, so each one is
 a link to the exact page and uses the words that page uses:
 
-1. Open Stripe's **API keys** page in test mode:
-   <https://dashboard.stripe.com/test/apikeys> (sign in, or create a Stripe
-   account when it asks). Under **Standard keys**, press **Reveal test key**
-   beside **Secret key** and copy it. It starts with `sk_test_`.
-2. Open this vibe's **Settings** tab on vibes.diy:
+1. Open this vibe's **Settings** tab on vibes.diy:
    `https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` (that is
-   **My Vibes** → this vibe → **Settings**). Under **Secrets**, enter the key
-   `STRIPE_SECRET_KEY` and paste the value, then save. From a terminal the
-   same thing is `npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe <ownerHandle>/<appSlug>`.
-3. Open Stripe's **Customer portal** settings in test mode:
+   **My Vibes** → this vibe → **Settings**), and press **Connect Stripe** under
+   **Payments**. Stripe opens its own setup pages: sign in with a Stripe login
+   or create one there, and answer Stripe's questions about the business. The
+   Stripe account belongs to the owner's Vibes DIY account and serves every
+   app they make, so it is connected once.
+2. Open Stripe's **Customer portal** settings in test mode, signed in to the
+   Stripe account you just connected:
    <https://dashboard.stripe.com/test/settings/billing/portal>. Under
    **Cancellations**, turn on **Cancel subscriptions** and choose **At end of
    billing period**, then press **Save**. The app sends members there to cancel
-   or change a card, and the portal does not exist until it is saved once.
-4. Go live. When a test payment goes through, switch to your live key to take
-   real payments: open Stripe's **API keys** page in live mode,
-   <https://dashboard.stripe.com/apikeys>, press **Reveal live key** beside
-   **Secret key** (it starts with `sk_live_`), set `STRIPE_SECRET_KEY` to it
-   the same way, and save the **Customer portal** once more in live mode at
+   or change a card, and the portal exists once it is saved.
+3. Come back to the app. The Join buttons work in test mode the moment both
+   items are done; the card `4242 4242 4242 4242` with any future date pays.
+4. Go live, one app at a time. Once a test payment goes through and live
+   payments are open on vibes.diy, press **Go live with Stripe** under
+   **Payments** on the Settings tab and finish Stripe's live setup (once, for
+   every app). Then press **Take live payments in this app** on this app's
+   Setup screen, and save the **Customer portal** once more in live mode at
    <https://dashboard.stripe.com/settings/billing/portal> — test-mode settings
-   stay in test mode. This step stays on the Setup screen after both items
-   are done, with a badge that reads *Test mode* until the live key is in.
+   stay in test mode, and the Setup screen links the portal page for the mode
+   the app is in. This step stays on the Setup screen after both items are
+   done, with a badge that reads *Test mode* until this app takes live
+   payments.
 
 Those steps are the items' copy on the Setup surface, with the vibe's real
 handle and slug filled in from the `ownerHandle` and `appSlug` the `/setup`
-route hands over. `https://dashboard.stripe.com/test/apikeys` for the key,
-`https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` for where it
-goes, `https://dashboard.stripe.com/test/settings/billing/portal` for the
-portal, and `STRIPE_SECRET_KEY` in so many words: "Open the Stripe dashboard"
-and "the Settings page" are directions to search for, and a person who has
-never seen either has to go looking. The portal item is checked with one read
+route hands over: `https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings`
+for **Connect Stripe**, and `https://dashboard.stripe.com/test/settings/billing/portal`
+for the portal. "Open the Stripe dashboard" and "the Settings page" are
+directions to search for, and a person who has never seen either has to go
+looking. The portal item is checked with one read
 of `GET /v1/billing_portal/configurations?is_default=true&active=true` — the
 active default is the configuration `/portal` opens, and a portal that was
-never saved has none — made only on the **owner's** `/setup` call and kept in
-a `setup` document the backend writes, so the owner sees the item turn to
-*Done* the moment they press Save and a visitor's read costs Stripe nothing. A
-refused read (a wrong key, a platform refusal, Stripe down) keeps the last
-verdict and rides the item as `problem`, which the Setup screen shows the
-owner in Stripe's own words; only a successful empty answer means not saved.
-A portal that was skipped answers a Stripe error whose message says so (§ 8).
-In the consumer flow, a Join button whose items are not done reads
-*Memberships are not open yet*; the owner's Setup entry is where the steps
-are, and later it is where the owner swaps the test key for the live one.
-
-## 2. The key never reaches the browser, and neither does Stripe.js
-
-Every Stripe request is made in backend.js with ctx.fetch and ctx.secrets.STRIPE_SECRET_KEY; App.jsx never calls api.stripe.com and never loads Stripe.js.
-
-The client talks to the app's own `/_api/...` routes, and the backend is the
-only place that knows the key exists. Stripe Checkout and the Customer Portal
-are pages Stripe hosts: the backend mints a URL, the page opens it, Stripe does
-the card, the retries, the invoices and the cancellation screen. Nothing about
-a card ever touches the app.
+never saved has none — made only on the **owner's** `/setup` call, in the mode
+the app charges in, and kept in a `setup` document per mode the backend
+writes, so the owner sees the item turn to *Done* the moment they press Save
+and a visitor's read costs Stripe nothing. A refused read (an account Stripe
+is still reviewing, a platform answer, Stripe down) keeps the last verdict and
+rides the item as `problem`, which the Setup screen shows the owner in its own
+words; only a successful empty answer means not saved. A portal that was
+skipped answers a Stripe error whose message says so (§ 8). In the consumer
+flow, a Join button whose items are not done reads *Memberships are not open
+yet*; the owner's Setup entry is where the steps are, and later it is where
+test turns into live.
+
+The owner pastes nothing: the platform holds the credential and attaches it to
+every call. An app made before Connect Stripe, whose `backend.js` already
+reads `ctx.secrets.STRIPE_SECRET_KEY`, keeps that helper as it is: an edit to
+it changes what was asked and leaves its memberships where they are (a
+subscription lives on the account that created it), and it moves to
+`ctx.stripe` only when the owner asks to switch to Connect Stripe. Every new
+membership app is built on `ctx.stripe`.
+
+### Test mode first, live when it opens
+
+`ctx.stripe.status()` answers `{ test: { available, state }, live: { available,
+state } }`: `available` is whether vibes.diy takes payments in that mode on
+this deployment, and `state` is the owner's account in it (`absent`,
+`onboarding`, `ready`, `disconnected`). The Stripe account serves every app
+the owner makes, so going live is the owner's choice per app:
+
+An app charges in live only after its owner chooses live for this app, and from then on live is its only account: a live account that is not ready closes checkout until the owner reconnects.
+
+The Join request carries the mode the member was shown, and the backend opens Checkout only when it matches the mode the app charges in now.
+
+The choice is a `setup:live` document the backend writes when the owner
+presses **Take live payments in this app**, offered once `live.state` reads
+`ready`; the mode comes from that document alone. `/setup` hands the `mode` to
+everyone and the Join request carries the mode the member was shown, so a
+page that still shows the other mode refreshes before any Checkout opens.
+While the mode is test, the Join button sits beside a *Test mode* badge, the
+owner sees the test card to rehearse with, and members read that test
+memberships end when the app goes live. The owner's Go-live step reads
+`live.available` (handed over as `liveOpen`) and `live.state` (as
+`liveReady`) to name the next button. The `stripe` skill's *Test mode first*
+section is the same rule in more words.
+
+## 2. Stripe stays on the server, and so does Stripe.js
+
+Every Stripe request is made in backend.js with ctx.stripe.fetch(path, { method, body, headers, mode }); App.jsx never calls api.stripe.com and never loads Stripe.js.
+
+The client talks to the app's own `/_api/...` routes, and the backend holds no
+Stripe credential at all: `ctx.stripe.fetch` sends the call to the platform,
+which attaches the key and the owner's account and hands back Stripe's own
+`Response`. The calls this recipe makes — a subscription-mode Checkout
+Session, reading it and the subscription back, the portal-configuration read
+and the portal session — are the calls `ctx.stripe` carries. Stripe Checkout
+and the Customer Portal are pages Stripe hosts: the backend mints a URL, the
+page opens it, Stripe does the card, the retries, the invoices and the
+cancellation screen. Nothing about a card ever touches the app.
 
 Checkout opens in a new tab with window.open, because the app runs inside a frame that cannot navigate the page around it.
 
@@ -100,12 +139,25 @@ Stripe opens in a new tab.
 ## 3. One membership, then one Checkout Session
 
 The membership exists before the money moves, and there is **one record per
-member**, `membership-<handle>`, rewritten in place by every attempt, renewal
-and lapse. `/subscribe` runs as the signed-in member (the page calls it with
-`apiFetch`), claims that record in `pending` with the plan — against the
+member per mode**, `membership-<mode>-<handle>`, rewritten in place by every
+attempt, renewal and lapse in that mode. `/subscribe` runs as the signed-in member (the page calls it with
+`apiFetch`), claims that record in `pending` with the plan and the mode — against the
 revision it just read, so a concurrent press conflicts and is handed the
 attempt that won — and asks Stripe for a session for exactly that record:
 
+Every membership records the mode it was made in, and every ctx.stripe.fetch call for that membership passes the membership's own mode.
+
+- The membership's `mode` is the app's current mode — test until the owner
+  takes this app live, live after — and the session, the subscription
+  read-back, the sweep and the portal all use the record's own `mode`. A test
+  membership is read from the test account for its whole life, and the
+  record for each mode is its own, so a test session still open when the app
+  goes live settles or expires on its own record. Only a record in the app's
+  current mode is entitled: after going live, the sweep writes every test
+  membership `entitled: false`, and the member joins fresh in live. (This
+  `mode` is the option `ctx.stripe.fetch` takes; the form's own
+  `mode=subscription` is Stripe's Checkout field.)
+- The whole payment lands in the owner's own Stripe account: the session carries the line items, the record's ids and the return URLs, and Stripe pays the merchant directly every period.
 - `mode=subscription`, with an inline recurring price:
   `line_items[0][price_data][recurring][interval]=month` (or `year`),
   `unit_amount` in the smallest unit, a product name. The owner never creates
@@ -132,7 +184,7 @@ portal (§ 7) to fix the card or cancel.
 
 The routes read the `club` database, which `access.js` binds, so `backend.js`
 declares `config.fetch.unfilteredReads` for it — and owes the obligation that
-comes with it: every route reads exactly one record, `membership-<caller>`,
+comes with it: every route reads exactly one record, `membership-<mode>-<caller>`,
 and no route lists memberships for anyone. The owner's roster is the page's
 own live query, scoped by the access function's `memberships` channel to the
 owner role.
@@ -157,7 +209,7 @@ fails. Nothing else about entitlement is configurable, on purpose:
   `current_period_start` is the moment the renewal was due, which is the
   moment the grace clock should start.
 - `canceled`, `unpaid`, `paused`, `incomplete` and `incomplete_expired` are
-  locked at once. With the portal set to cancel at period end (§ 1 step 3), a
+  locked at once. With the portal set to cancel at period end (§ 1 step 2), a
   cancellation never cuts into paid time, because Stripe keeps the status
   `active` until the period closes.
 
@@ -193,7 +245,8 @@ the same rule whatever the page shows.
 
 ## 6. Two things keep the mirror true: the return, and the sweep
 
-Both are the backend reading Stripe with the key.
+Both are the backend reading Stripe through `ctx.stripe`, in the membership's
+own mode.
 
 - **The return.** When the app opens with `#subscribed=<id>` in its address,
   the page calls `/confirm`; the route reads the Checkout Session back, takes
@@ -214,7 +267,7 @@ A scheduled sweep refreshes every live subscription from Stripe, so a failed ren
 
 Why not a webhook: a webhook write arrives with no identity and would need
 `allowAnonymous` on the one record that grants access. Reading the
-subscription back with the key the app already holds is the same proof from
+subscription back through `ctx.stripe` is the same proof from
 the same source, on a route that can only write what Stripe reports.
 
 ## 7. Cancel, change a card, see invoices: the Customer Portal
@@ -236,13 +289,16 @@ with a sign-in error.
 
 ## 8. Errors keep their reason
 
-Stripe's refusals come back as JSON with `error.message`; return it as
-`{ ok: false, reason: "stripe", message }` so the page can show the owner
-*why*. The portal's "No configuration provided" message is the one that means
-step 3 of setup was skipped. A refused `ctx.fetch` — the
-`{ vibesEgressDenied: true }` shape — is a platform refusal; log it and answer
-`{ ok: false, reason: "unavailable" }`. `api.stripe.com` is CORS-open to the
-app's origin, so nothing here needs the curated list.
+Stripe's own answers arrive as a `Response` whose JSON carries
+`error.message`; return it as `{ ok: false, reason: "stripe", message }` so
+the page can show *why*. The portal's "No configuration provided" message is
+the one that means step 2 of setup is still to do. A platform answer is thrown
+as an `Error` with `e.reason`, and each reason names the owner's next step:
+`not_connected` and `not_ready` are the Connect Stripe item,
+`account_disconnected` is **Connect Stripe** again from the same Settings tab,
+and `not_available` means payments in that mode are paused on vibes.diy for
+now. Log it with `ctx.log` and hand the reason to the page, which reads it as
+*Memberships are not open yet*.
 
 ## Complete backend.js
 
@@ -255,11 +311,10 @@ app's origin, so nothing here needs the curated list.
 export const config = {
   scheduled: { interval: "30m" },
   // The routes read the member's own record; access.js binds the database, so the fetch lane needs
-  // this declaration, and every route owes the check it waives: it reads membership-<caller> only.
-  fetch: { unfilteredReads: { dbs: ["club"], why: "the /subscribe, /confirm, /refresh and /portal routes read the signed-in member's own membership record, membership-<their handle>, and nothing else" } },
+  // this declaration, and every route owes the check it waives: it reads membership-<mode>-<caller> only.
+  fetch: { unfilteredReads: { dbs: ["club"], why: "the /subscribe, /confirm, /refresh and /portal routes read the signed-in member's own membership record in the app's current mode, membership-<mode>-<their handle>, and nothing else" } },
 };
 
-const STRIPE = "https://api.stripe.com/v1";
 const DB = "club";
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 // The one knob: how long a past_due member stays in while Stripe retries the card. Zero locks
@@ -280,43 +335,61 @@ function appUrl(ctx, hash) {
   return `https://vibes.diy/vibe/${ctx.appInfo.ownerHandle}/${ctx.appInfo.appSlug}${hash}`;
 }
 
-// One record per member, named for them: every attempt, renewal and lapse rewrites it in place.
-function membershipId(handle) {
-  return `membership-${handle}`;
+// One record per member per mode, named for them: every attempt, renewal and lapse in that mode
+// rewrites it in place, and a test record never shares a document with a live one.
+function membershipId(handle, mode) {
+  return `membership-${mode}-${handle}`;
 }
 
-async function stripe(ctx, method, path, form, headers = {}) {
-  const key = ctx.secrets.STRIPE_SECRET_KEY;
-  if (!key) return { ok: false, reason: "missing-key" };
-  const res = await ctx.fetch(`${STRIPE}${path}`, {
-    method,
-    headers: { authorization: `Bearer ${key}`, ...(form ? { "content-type": "application/x-www-form-urlencoded" } : {}), ...headers },
-    body: form ? form.toString() : undefined,
-  });
-  const body = await res.json().catch(() => null);
-  if (!res.ok) {
-    if (body?.vibesEgressDenied) {
-      ctx.log("warn", "stripe egress denied", { gate: body.gate });
-      return { ok: false, reason: "unavailable" };
-    }
-    return { ok: false, reason: "stripe", message: body?.error?.message ?? `HTTP ${res.status}` };
+// The owner's choice to take THIS app live. The Stripe account is the owner's and serves all of
+// their apps, so its live account turning ready never moves an app by itself.
+const LIVE_CHOICE = "setup:live";
+
+// Which of the owner's two Stripe accounts this app charges in, decided by the owner's choice
+// alone; then whether that account takes card payments right now. A live app whose live account
+// is not ready stays live with checkout closed until the owner reconnects.
+async function checkoutMode(ctx) {
+  const mode = (await ctx.db.get(LIVE_CHOICE, { db: DB })) ? "live" : "test";
+  let st;
+  try {
+    st = await ctx.stripe.status();
+  } catch (e) {
+    ctx.log("warn", "stripe status unavailable", { message: e.message });
+    return { mode, open: false, state: "unavailable", liveOpen: false, liveReady: false };
   }
+  return { mode, open: st[mode].state === "ready", state: st[mode].state, liveOpen: st.live.available, liveReady: st.live.state === "ready" };
+}
+
+// One call to Stripe on the owner's account, in the membership's own mode. Form-encoded in,
+// Stripe's JSON out, the refusal's own sentence kept.
+async function stripe(ctx, mode, method, path, form, headers = {}) {
+  let res;
+  try {
+    res = await ctx.stripe.fetch(`/v1${path}`, { method, body: form, headers, mode });
+  } catch (e) {
+    // The platform's answer, not Stripe's: a Setup step for the owner, or payments paused.
+    ctx.log("warn", "stripe call refused", { reason: e.reason });
+    return { ok: false, reason: e.reason ?? "not_available" };
+  }
+  const body = await res.json().catch(() => null);
+  if (!res.ok) return { ok: false, reason: "stripe", message: body?.error?.message ?? `HTTP ${res.status}` };
   return { ok: true, body };
 }
 
-// Has the owner saved the Customer portal? Stripe is asked only on the OWNER's call, and the answer
-// is kept in a document the backend writes, so a visitor's /setup read never reaches Stripe and a
-// blip at Stripe keeps the last verdict. The /portal route opens the ACTIVE DEFAULT configuration,
-// so that is the one asked for; a refused read is a problem shown to the owner, never "not saved".
-const PORTAL_STATE = "setup:stripe-portal";
-async function portalSaved(ctx, owner) {
-  const kept = await ctx.db.get(PORTAL_STATE, { db: DB });
+// Has the owner saved the Customer portal in this mode? Stripe is asked only on the OWNER's call,
+// and the answer is kept in a document per mode the backend writes, so a visitor's /setup read never
+// reaches Stripe and a blip at Stripe keeps the last verdict. The /portal route opens the ACTIVE
+// DEFAULT configuration, so that is the one asked for; a refused read is a problem shown to the
+// owner, never "not saved". Test-mode portal settings stay in test mode, so live asks again.
+const portalState = (mode) => `setup:stripe-portal:${mode}`;
+async function portalSaved(ctx, owner, mode, connected) {
+  const kept = await ctx.db.get(portalState(mode), { db: DB });
   const known = kept?.saved === true;
-  if (!owner || !ctx.secrets.STRIPE_SECRET_KEY) return { done: known };
-  const configurations = await stripe(ctx, "GET", "/billing_portal/configurations?is_default=true&active=true&limit=1");
+  if (!owner || !connected) return { done: known };
+  const configurations = await stripe(ctx, mode, "GET", "/billing_portal/configurations?is_default=true&active=true&limit=1");
   if (!configurations.ok) return { done: known, problem: configurations.message ?? "Stripe could not be reached; the last verdict stands." };
   const saved = (configurations.body.data?.length ?? 0) > 0;
-  if (known !== saved) await ctx.db.put({ _id: PORTAL_STATE, type: "setup", saved, checkedAt: Date.now() }, { db: DB, id: PORTAL_STATE, ifRev: kept?._rev });
+  if (known !== saved) await ctx.db.put({ _id: portalState(mode), type: "setup", mode, saved, checkedAt: Date.now() }, { db: DB, id: portalState(mode), ifRev: kept?._rev });
   return { done: saved };
 }
 
@@ -339,13 +412,14 @@ function isEntitled(m, now = Date.now()) {
 }
 
 // Re-read the member's subscription and write the record back when anything the app keeps
-// changed — including entitlement lapsing with nothing new at Stripe.
-async function refresh(ctx, m) {
+// changed — including entitlement lapsing with nothing new at Stripe, and a record whose mode the
+// app has moved past (`appMode`), which grants nothing however Stripe sees it.
+async function refresh(ctx, m, appMode) {
   if (!m.subscriptionId) return m;
-  const sub = await stripe(ctx, "GET", `/subscriptions/${m.subscriptionId}`);
+  const sub = await stripe(ctx, m.mode, "GET", `/subscriptions/${m.subscriptionId}`);
   if (!sub.ok) return m; // a refusal changes nothing; the next read tries again
   const next = { ...m, ...mirror(sub.body), syncedAt: Date.now() };
-  next.entitled = isEntitled(next);
+  next.entitled = isEntitled(next) && m.mode === appMode;
   const changed = ["status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd", "entitled"].some((k) => next[k] !== m[k]);
   if (!changed) return m;
   await ctx.db.put(next, { db: DB, id: m._id, ifRev: m._rev });
@@ -354,7 +428,7 @@ async function refresh(ctx, m) {
 
 // A record still waiting on its Checkout Session: bind the subscription Stripe created, or expire
 // the attempt after a day.
-async function settlePending(ctx, m) {
+async function settlePending(ctx, m, appMode) {
   if (m.status !== "pending") return m;
   if (!m.sessionId) {
     if (Date.now() - m.sessionCreatedAt > SESSION_TTL_MS) {
@@ -364,7 +438,7 @@ async function settlePending(ctx, m) {
     }
     return m;
   }
-  const session = await stripe(ctx, "GET", `/checkout/sessions/${m.sessionId}`);
+  const session = await stripe(ctx, m.mode, "GET", `/checkout/sessions/${m.sessionId}`);
   if (!session.ok) return m;
   const s = session.body;
   if (s.id !== m.sessionId || s.client_reference_id !== m._id) {
@@ -379,7 +453,7 @@ async function settlePending(ctx, m) {
   if (!s.subscription) return m; // not completed yet
   const bound = { ...m, subscriptionId: s.subscription, customerId: s.customer };
   await ctx.db.put(bound, { db: DB, id: m._id, ifRev: m._rev });
-  return refresh(ctx, await ctx.db.get(m._id, { db: DB }));
+  return refresh(ctx, await ctx.db.get(m._id, { db: DB }), appMode);
 }
 
 export async function fetch(request, ctx) {
@@ -390,27 +464,43 @@ export async function fetch(request, ctx) {
   // links with) for the owner alone.
   if (url.pathname === "/setup" && request.method === "GET") {
     const owner = me === ctx.appInfo.ownerHandle;
-    const items = [
-      { id: "stripe-key", label: "Stripe secret key", done: Boolean(ctx.secrets.STRIPE_SECRET_KEY) },
-      { id: "stripe-portal", label: "Customer portal", ...(await portalSaved(ctx, owner)) },
-    ];
+    const { mode, open, state, liveOpen, liveReady } = await checkoutMode(ctx);
+    const connect = { id: "stripe-connect", label: "Connect Stripe", done: open, state };
+    if (mode === "live" && !liveOpen) connect.problem = "Vibes DIY has paused live payments for now; memberships reopen here by themselves when they return.";
+    const items = [connect, { id: "stripe-portal", label: "Customer portal", ...(await portalSaved(ctx, owner, mode, open)) }];
     const ready = items.every((item) => item.done);
-    if (!owner) return json({ ok: true, ready, owner });
-    // `live` is the Go-live step's badge: a test key takes test payments, a live key real ones.
-    const live = (ctx.secrets.STRIPE_SECRET_KEY ?? "").startsWith("sk_live_");
-    return json({ ok: true, ready, owner, live, items, graceDays: GRACE_DAYS, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+    // `mode` is everyone's: the Join button wears a Test mode badge while the app takes test payments.
+    if (!owner) return json({ ok: true, ready, owner, mode });
+    // The Go-live step: `liveOpen` (vibes.diy takes live payments) and `liveReady` (the owner's live
+    // Stripe account is ready, so this app can be taken live).
+    return json({ ok: true, ready, owner, mode, liveOpen, liveReady, items, graceDays: GRACE_DAYS, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+  }
+
+  // The owner takes this app live: one document, written for the owner alone, once their live
+  // Stripe account is ready. From here on the app charges in live only.
+  if (url.pathname === "/go-live" && request.method === "POST") {
+    if (me !== ctx.appInfo.ownerHandle) return json({ ok: false, reason: "owner-only" }, 403);
+    const { liveReady } = await checkoutMode(ctx);
+    if (!liveReady) return json({ ok: false, reason: "not_ready" }, 409);
+    const chosen = await ctx.db.get(LIVE_CHOICE, { db: DB });
+    if (!chosen) await ctx.db.put({ _id: LIVE_CHOICE, type: "setup", mode: "live", chosenAt: Date.now() }, { db: DB, id: LIVE_CHOICE });
+    return json({ ok: true, mode: "live" });
   }
 
   if (!me) return json({ ok: false, reason: "sign-in" }, 401);
-  const id = membershipId(me);
-  const current = await ctx.db.get(id, { db: DB }); // null before the first attempt
+  const { mode, open, state } = await checkoutMode(ctx);
+  const id = membershipId(me, mode); // the member's record in the mode the app charges in now
+  const current = await ctx.db.get(id, { db: DB }); // null before the first attempt in this mode
 
   if (url.pathname === "/subscribe" && request.method === "POST") {
-    if (!ctx.secrets.STRIPE_SECRET_KEY) return json({ ok: false, reason: "missing-key" }, 503);
-    // The portal is where a member cancels, so nobody joins before it exists: the KEPT verdict,
-    // never a Stripe read per press.
-    if ((await ctx.db.get(PORTAL_STATE, { db: DB }))?.saved !== true) return json({ ok: false, reason: "setup-incomplete" }, 503);
-    const { plan } = await request.json();
+    const { plan, mode: shown } = await request.json();
+    // The member joins in the mode their page showed them, or not at all: a page that still shows
+    // the other mode refreshes first.
+    if (shown !== mode) return json({ ok: false, reason: "mode-changed", mode }, 409);
+    if (!open) return json({ ok: false, reason: state === "disconnected" ? "account_disconnected" : "not_ready" }, 503);
+    // The portal is where a member cancels, so nobody joins before it exists: the KEPT verdict for
+    // this mode, never a Stripe read per press.
+    if ((await ctx.db.get(portalState(mode), { db: DB }))?.saved !== true) return json({ ok: false, reason: "setup-incomplete" }, 503);
     const price = PLANS[plan];
     if (!price) return json({ ok: false, reason: "unknown-plan" }, 400);
     // A subscription that is live at Stripe — entitled or not — is managed in the portal, never
@@ -429,10 +519,11 @@ export async function fetch(request, ctx) {
       plan,
       amount: price.amount,
       currency: price.currency,
+      mode, // the account this membership is made in; every later call for it passes the same mode
       status: "pending",
       entitled: false,
       attempt,
-      customerId: current?.customerId, // a returning member keeps their Stripe customer
+      customerId: current?.customerId, // a returning member keeps their Stripe customer in this mode
       sessionId: undefined,
       sessionUrl: undefined,
       subscriptionId: undefined,
@@ -463,7 +554,7 @@ export async function fetch(request, ctx) {
     });
     // The idempotency key names the attempt, so two first presses that both got past the claim
     // (a record that does not exist yet has no revision to claim) mint ONE session at Stripe.
-    const session = await stripe(ctx, "POST", "/checkout/sessions", form, { "idempotency-key": `${id}:${attempt}` });
+    const session = await stripe(ctx, mode, "POST", "/checkout/sessions", form, { "idempotency-key": `${id}:${attempt}` });
     if (!session.ok) return json(session, session.reason === "stripe" ? 502 : 503);
     const claimed = await ctx.db.get(id, { db: DB });
     await ctx.db.put({ ...claimed, sessionId: session.body.id, sessionUrl: session.body.url }, { db: DB, id, ifRev: claimed._rev });
@@ -473,14 +564,14 @@ export async function fetch(request, ctx) {
   // Back from Checkout: bind the subscription and mirror it.
   if (url.pathname === "/confirm" && request.method === "POST") {
     if (!current) return json({ ok: false, reason: "not-found" }, 404);
-    const settled = await settlePending(ctx, current);
+    const settled = await settlePending(ctx, current, mode);
     return json({ ok: true, status: settled.status, entitled: settled.entitled === true });
   }
 
   // Back from the portal, or a "check again": re-read my subscription now.
   if (url.pathname === "/refresh" && request.method === "POST") {
     if (!current?.subscriptionId) return json({ ok: true, entitled: false });
-    const next = await refresh(ctx, current);
+    const next = await refresh(ctx, current, mode);
     return json({ ok: true, status: next.status, entitled: next.entitled === true });
   }
 
@@ -488,7 +579,7 @@ export async function fetch(request, ctx) {
   if (url.pathname === "/portal" && request.method === "POST") {
     if (!current?.customerId) return json({ ok: false, reason: "no-membership" }, 404);
     const form = new URLSearchParams({ customer: current.customerId, return_url: appUrl(ctx, "#portal") });
-    const portal = await stripe(ctx, "POST", "/billing_portal/sessions", form);
+    const portal = await stripe(ctx, current.mode, "POST", "/billing_portal/sessions", form);
     if (!portal.ok) return json(portal, portal.reason === "stripe" ? 502 : 503);
     return json({ ok: true, url: portal.body.url });
   }
@@ -498,14 +589,14 @@ export async function fetch(request, ctx) {
 
 // The sweep: every live subscription re-read, entitlement recomputed, pending attempts settled.
 export async function scheduled(event, ctx) {
-  if (!ctx.secrets.STRIPE_SECRET_KEY) return;
+  const { mode } = await checkoutMode(ctx); // records in any other mode are re-read and grant nothing
   let after;
   let changed = 0;
   do {
     const page = await ctx.db.query({ db: DB, field: "type", key: "membership", limit: 100, after });
     for (const m of page) {
       if (TERMINAL.has(m.status) || m.status === "expired") continue;
-      const next = m.status === "pending" ? await settlePending(ctx, m) : await refresh(ctx, m);
+      const next = m.status === "pending" ? await settlePending(ctx, m, mode) : await refresh(ctx, m, mode);
       if (next !== m) changed += 1;
     }
     after = page.next;
@@ -526,12 +617,12 @@ export function club(doc, oldDoc, user, ctx) {
 
   // One membership record per member, named for them, written only by backend.js.
   if (doc.type === "membership") {
-    if (doc._id !== `membership-${doc.memberHandle}`) throw { forbidden: "a membership is named for its member" };
+    if (doc._id !== `membership-${doc.mode}-${doc.memberHandle}`) throw { forbidden: "a membership is named for its mode and its member" };
     if (oldDoc) {
       // Only backend.js changes an existing membership — claiming an attempt, binding the session,
       // mirroring Stripe, recomputing entitlement — so neither status nor entitled is a member's to edit.
       ctx.requireBackend();
-      if (doc.memberHandle !== oldDoc.memberHandle) throw { forbidden: "a membership keeps its member" };
+      if (doc.memberHandle !== oldDoc.memberHandle || doc.mode !== oldDoc.mode) throw { forbidden: "a membership keeps its member and its mode" };
     } else {
       if (doc.memberHandle !== user.userHandle) throw { forbidden: "a membership belongs to its member" };
       if (doc.status !== "pending" || doc.entitled) throw { forbidden: "a membership starts pending" };
@@ -572,10 +663,10 @@ import { apiFetch, useViewer } from "use-vibes";
 import { Badge, Button, Heading, Row, Stack, Text } from "@vibes.diy/pouf";
 
 // The setup verdict, read on mount and again whenever the app comes back into view: the owner
-// sets the key or saves the portal in another tab and returns, and the Join buttons unlock without
-// a reload.
+// connects Stripe or saves the portal in another tab and returns, and the Join buttons unlock
+// without a reload.
 function useSetup() {
-  const [setup, setSetup] = useState(null); // { ready, owner, items?, graceDays?, ownerHandle?, appSlug? }
+  const [setup, setSetup] = useState(null); // { ready, owner, mode, liveOpen?, items?, graceDays?, ownerHandle?, appSlug? }
   const latest = useRef(0);
   useEffect(() => {
     // Mount, focus and visibility reads overlap; only the latest one may land, or a slow stale
@@ -588,39 +679,44 @@ function useSetup() {
     const onVisible = () => { if (document.visibilityState === "visible") load(); };
     document.addEventListener("visibilitychange", onVisible);
     window.addEventListener("focus", load);
-    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
+    window.addEventListener("setup-changed", load); // the Setup screen's own Take live button
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); window.removeEventListener("setup-changed", load); };
   }, []);
   return setup;
 }
 
+// The button the Settings tab shows for each state of the owner's Stripe account, in its own words.
+const STRIPE_BUTTON = { absent: "Connect Stripe", onboarding: "Finish Stripe setup", disconnected: "Connect Stripe again" };
+
 // The Setup surface, the owner's alone: two items, every step a link to the exact page in that
 // page's own words, with this vibe's real handle and slug filled in.
+
 function SetupScreen({ setup }) {
   const vibe = `${setup.ownerHandle}/${setup.appSlug}`;
   const settingsUrl = `https://vibes.diy/vibes/mine/${vibe}/settings`;
+  const live = setup.mode === "live";
+  // The portal page for the mode this app charges in: test-mode settings stay in test mode.
+  const portalUrl = live ? "https://dashboard.stripe.com/settings/billing/portal" : "https://dashboard.stripe.com/test/settings/billing/portal";
+  const connect = setup.items.find((i) => i.id === "stripe-connect");
+  const takeLive = () => apiFetch("/go-live", { method: "POST" }).then(() => window.dispatchEvent(new Event("setup-changed")));
   return (
     <Stack>
       <Heading>Setup</Heading>
       {setup.items.map((item) => (
         <Row key={item.id} gap={2}>
           <Text>{item.label}</Text>
-          <Badge tone={item.done ? "up" : "info"}>{item.done ? "Done" : "To do"}</Badge>
+          <Badge tone={item.done ? "up" : "info"}>{item.done ? "Done" : item.state === "onboarding" ? "Stripe is finishing up" : "To do"}</Badge>
           {item.problem && <Text muted>{item.problem}</Text>}
         </Row>
       ))}
       <ol>
         <li>
-          Open Stripe's <a href="https://dashboard.stripe.com/test/apikeys" target="_blank" rel="noreferrer">API keys page (test mode)</a>,
-          use your Stripe account (the page offers to create one), and under <b>Standard keys</b> press <b>Reveal test key</b> beside <b>Secret key</b>.
-          Copy it; it starts with <code>sk_test_</code>.
+          Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings)
+          and press <b>{STRIPE_BUTTON[connect.state] ?? "Connect Stripe"}</b> under <b>Payments</b>.
+          Stripe opens its own setup pages: use your Stripe account, or create one there. Your Stripe account serves every app you make.
         </li>
         <li>
-          Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings).
-          Under <b>Secrets</b>, enter the key <code>STRIPE_SECRET_KEY</code>, paste the value, and save.
-          From a terminal instead: <code>npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe {vibe}</code>.
-        </li>
-        <li>
-          Open Stripe's <a href="https://dashboard.stripe.com/test/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings</a>:
+          Signed in to that Stripe account, open its <a href={portalUrl} target="_blank" rel="noreferrer">Customer portal settings ({live ? "live" : "test"} mode)</a>:
           under <b>Cancellations</b> turn on <b>Cancel subscriptions</b>, choose <b>At end of billing period</b>, and press <b>Save</b>.
           Members use that page to cancel or change a card.
         </li>
@@ -628,12 +724,27 @@ function SetupScreen({ setup }) {
           Come back here: the Join buttons work as soon as both items are done. In test mode the card 4242 4242 4242 4242 pays.
         </li>
         <li>
-          {/* The Go-live step stays here once the items are done; its badge says which key is in. */}
-          <Badge tone={setup.live ? "up" : "info"}>{setup.live ? "Live" : "Test mode"}</Badge>{" "}
-          When a test payment goes through, switch to your live key to take real payments: open Stripe's{" "}
-          <a href="https://dashboard.stripe.com/apikeys" target="_blank" rel="noreferrer">API keys page (live mode)</a>, press <b>Reveal live key</b> beside <b>Secret key</b>
-          (it starts with <code>sk_live_</code>), set <code>STRIPE_SECRET_KEY</code> to it the same way, and save the{" "}
-          <a href="https://dashboard.stripe.com/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings (live mode)</a> once more.
+          {/* The Go-live step stays here once the items are done; its badge says which account this app charges in. */}
+          <Badge tone={live ? "up" : "info"}>{live ? "Live" : "Test mode"}</Badge>{" "}
+          {live ? (
+            <>
+              Real memberships bill into your Stripe account; refunds, invoices and payouts are in your Stripe Dashboard. Keep the{" "}
+              <a href={portalUrl} target="_blank" rel="noreferrer">Customer portal settings (live mode)</a> saved.
+            </>
+          ) : setup.liveReady ? (
+            <>
+              Your live Stripe account is ready. Each app goes live on its own, so this one rehearses until you press{" "}
+              <Button onClick={takeLive}>Take live payments in this app</Button>, then save the{" "}
+              <a href="https://dashboard.stripe.com/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings (live mode)</a> once more.
+            </>
+          ) : setup.liveOpen ? (
+            <>
+              When a test payment goes through, press <b>Go live with Stripe</b> under <b>Payments</b> on{" "}
+              <a href={settingsUrl} target="_blank" rel="noreferrer">the same Settings tab</a> and finish Stripe's live setup, once for all your apps; then come back here to take this app live.
+            </>
+          ) : (
+            <>Test mode runs the whole flow end to end. The <b>Go live with Stripe</b> button appears under <b>Payments</b> on the same Settings tab when vibes.diy opens live payments.</>
+          )}
         </li>
       </ol>
     </Stack>
@@ -678,7 +789,12 @@ export default function App() {
       const data = await res.json();
       if (!data.ok) {
         tab.close();
-        setError(data.reason === "stripe" ? data.message : data.reason === "already-member" ? "You already have a membership — manage it below." : "Memberships are not open yet.");
+        setError(
+          data.reason === "stripe" ? data.message
+          : data.reason === "already-member" ? "You already have a membership — manage it below."
+          : data.reason === "mode-changed" ? `Memberships here just moved to ${data.mode} mode. Refresh the page and press Join again.`
+          : "Memberships are not open yet."
+        );
         return;
       }
       tab.location.href = data.url;
@@ -688,7 +804,8 @@ export default function App() {
   };
 
   const ready = setup?.ready === true;
-  const mine = viewer ? memberships.find((m) => m._id === `membership-${viewer.userHandle}`) : undefined;
+  // The member's record in the mode the app charges in now: a record from the other mode is a rehearsal.
+  const mine = viewer && setup ? memberships.find((m) => m._id === `membership-${setup.mode}-${viewer.userHandle}`) : undefined;
   const entitled = mine?.entitled === true;
   const ends = mine?.currentPeriodEnd ? new Date(mine.currentPeriodEnd).toLocaleDateString() : null;
 
@@ -721,9 +838,18 @@ export default function App() {
               {mine?.subscriptionId && mine.status !== "canceled" ? (
                 <Text>Your last payment did not go through. Update your card below to keep reading.</Text>
               ) : ready ? (
-                <Button onClick={() => openStripe("/subscribe", { plan: "monthly" })} disabled={busy} loading={busy}>
-                  Join — Stripe opens in a new tab
-                </Button>
+                <Stack>
+                  {/* Test mode is a rehearsal: the owner gets the test card, members learn it ends at go-live. */}
+                  {setup.mode === "test" && (
+                    <Row gap={2}>
+                      <Badge tone="info">Test mode</Badge>
+                      <Text muted>{setup.owner ? "Join with the test card 4242 4242 4242 4242 and any future date." : "This is a rehearsal: test memberships end when the app goes live."}</Text>
+                    </Row>
+                  )}
+                  <Button onClick={() => openStripe("/subscribe", { plan: "monthly", mode: setup.mode })} disabled={busy} loading={busy}>
+                    Join — Stripe opens in a new tab
+                  </Button>
+                </Stack>
               ) : (
                 <Text muted>Memberships are not open yet.</Text>
               )}
@@ -745,7 +871,7 @@ export default function App() {
           {setup?.owner && (
             <ul>
               {memberships.map((m) => (
-                <li key={m._id}>@{m.memberHandle} · {m.plan} · {m.status}{m.entitled ? " · entitled" : ""}{m.currentPeriodEnd ? ` · until ${new Date(m.currentPeriodEnd).toLocaleDateString()}` : ""}</li>
+                <li key={m._id}>@{m.memberHandle} · {m.mode} · {m.plan} · {m.status}{m.entitled ? " · entitled" : ""}{m.currentPeriodEnd ? ` · until ${new Date(m.currentPeriodEnd).toLocaleDateString()}` : ""}</li>
               ))}
             </ul>
           )}