Billing
Billing records the plan each forge is on (src/billing/): a store of entitlements, every change kept. There is no payment processor and nothing reads a plan to limit a forge yet; a grant is a record until a limit reads it.
- Plans: small, medium or large, the sizes. A forge never granted a plan reads as
activeon its size, sourcegranted. - Grant by hand (admin, a person): the Billing page, the terminal screen,
PUT /api/v1/forges/{name}/planwith{ "plan": "large" }(GETreads it), or the MCPforgestool with{ forge, plan }(planned first;dryRun: falsegrants). - Preview first: the page's Review change opens
/settings/billing/change?forge=&plan=, which says in one linesmall → medium: $49.00 a month, starts 2026-11-15(from, to, whole cents a month from the plans setting, the UTC day it starts) and carries those numbers in its Confirm change form. A confirm whose numbers differ from what the preview would say now (a price edited, the day rolled over) changes nothing and shows the new preview (409). The terminal's yes/no shows the same line; no Stripe call is made (src/billing/plan_change.ts). - Audit: every grant is a row in
entitlement_changeand abilling.planevent. - Terminal: the palette's Billing (admins),
src/tui/screens/billing.ts:j/kpick a forge,s,morlgrants that plan after a yes/no;cconnects Stripe (key shown as dots),wsaves a signing secret,xdisconnects after a yes/no. - Stripe (#11136): Settings → Billing → Provider takes one key (
src/billing/stripe.ts,connection.ts); how to connect it is indocs/PROFIT.md. Not yet: the/hooks/stripereceiver, and checkout, portal and reconcile, which come with the pull that calls them.
Gift codes
A code gives a plan for free, with or without a payment provider (src/billing/codes.ts, src/actions/codes.ts). No provider is asked: a redeemed code writes the entitlement itself, source code:<id>.
- Make (admin, a person): Settings → Billing → Codes (below Plans) → Make a code, the terminal's Gift codes screen (
nmakes,ppicks the plan,xrevokes after a yes; live, so a code made or redeemed anywhere shows at once) (plan, uses, note, expiry),POST /api/v1/codes(dryRuntrue unlessfalse), or the MCPforgestool withcode: { plan, uses?, note?, expires? }. The plain code (forge-7kq4-m2xp) and its link…/?code=<code>are shown once; only a hash is kept. - List / revoke: the same page (one row per code: plan and note, used of limit, who redeemed, and one Stop this code working button),
GET /api/v1/codes,DELETE /api/v1/codes/{id}, MCPcodes: true/revoke: <id>. Revoking stops new uses; forges already made keep their plan. - Redeem: the link moves the code into an HttpOnly cookie and opens
/forges/new(no code in the address, the log or the history) with the code filled in ("A gift: a medium forge, free."; the admin is not named). Without a code the field sits behind a "Have a code?" disclosure;POST /api/v1/forgesand the MCPspawntakecode. A wrong, used-up, expired or revoked code is said on the same form. A client may try 10 codes in 10 minutes. - Audit:
billing.code.make,billing.code.redeem,billing.code.revokeevents.
Payments kept
Each invoice the verified Stripe webhook tells of is one payment row (src/billing/payments.ts, #13092): the invoice id, customer, amount in Stripe's integer minor units and its currency, both as sent, status paid, failed or refunded, and when.
- Events:
invoice.paid,invoice.payment_failed,charge.refunded. A malformed one answers 200 and is audited asbilling.payment_refused. - Order: Stripe does not promise it. An event older than the row's own changes nothing, so a late
payment_failedcannot undopaid. - Refunds: only a charge refunded in full marks the invoice
refunded; a partial refund leaves it. A refund seen before its invoice is kept and applied when the row arrives. A refunded row stays refunded. A charge not tied to an invoice changes nothing and is not audited. - Retries: the row is written in the same transaction as the event id; if the write fails the id is not kept and Stripe retries.
- Where to see it: Settings → Billing, "Payments kept" (count and refunded); the terminal's Billing screen shows the newest payment on each forge's line.
What a paid forge is, at /terms (#13207)
Open /terms, signed out or in. It opens with one sentence of purpose and then five labelled rows: what you buy, what happens if a payment lapses, who owns the data, how to cancel, and what the forge keeps about a visitor. /pricing and /signup link to it.
- Lapse: the grace days and the retention days are the
billing.grace_daysandbilling.retention_dayssettings, read when the page is drawn, so changing a setting changes the page. Sleeping never deletes anything; the data waits the retention days, then the operator may remove it, so ask for an export first. - Terminal: palette → "Terms of a paid forge" (
src/tui/screens/terms.ts). It shows the same rows; Esc goes back. - Code: the sentences are one function,
termRowsinsrc/billing/terms_words.ts, read bysrc/web/pages/terms.tsand the terminal screen, so they cannot drift. - Test:
bun test test/terms-page.test.ts test/tui-terms.test.ts. - The owner's payments:
/settings/payments(linked from Settings) and the terminal's Payments palette entry (src/tui/screens/payments.ts) list what was charged for the forges the person claimed, newest first: status word, date, amount in its currency and the forge's plan now (the store keeps no plan per payment). Both readpaymentsForinsrc/web/pages/payments.ts, so each shows only the person's own forges. At most 100 rows; past that a sentence says older ones are not listed. Try it: sign in, Settings → Payments. Pinned bytest/payments-page.test.tsandtest/payments-tui.test.ts.