flagon-io/g1t

public

g1t/docs/BILLING_OPERATIONS.md

1,124 lines72,873 bytesCode Blame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	1	# Billing operations: costs, margin and prices
	2
	3	How g1t checks what it charges against what Cloudflare charges it, keeps
	4	prices at cost plus 20%, and tells staff when the margin slips. Internal.
	5	Code: `services/billing/src/costs.rs` (reading the bill), `margin.rs`
	6	(reconciliation, drift, alerts), `pricing.rs` (versions, proposals,
Spend caps: a monthly budget for comped workspaces and a daily breaker on what g1t pays2d ago	7	notice), `keeper.rs` (sandbox and Workers for Platforms measurements),
	8	`budget.rs` (what g1t pays for itself, and its caps; see
	9	[Spend caps](#spend-caps)).
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	10	Page: sudo Costs & margin (`/costs`).
	11
	12	Several Cloudflare products g1t runs on are new. Artifacts bills
	13	"operations" from 2026-10-14 without defining them (see
	14	[ARTIFACTS.md](ARTIFACTS.md), M1). So nothing here hard-codes a product
	15	list or a unit: every line Cloudflare bills is kept, and how a line maps
	16	to what g1t sells is data you change from sudo, without a deploy.
	17
	18	## Data sources
	19
	20	\| Source \| What \| Where it lands \|
	21	\| --- \| --- \| --- \|
	22	\| Billable usage, `GET /accounts/{account}/billable-usage?from=&to=` \| One row per service per day in FOCUS columns: `ServiceFamilyName`, `ServiceName`, `ChargePeriodStart`, `PricingQuantity`, `ContractedCost` / `BilledCost` / `ListCost`. Every product g1t uses appears once it is used: Workers, Workers for Platforms, D1, KV, R2, Queues, Containers, Durable Objects, Artifacts, Browser Rendering, Workers AI, Vectorize, Cloudflare for SaaS, Email. Inside an included amount the cost is 0. \| `cost_lines`, source `billable_usage` \|
Costs: Cloudflare's count for a pull request's working copy is shared out to its repository's workspace (repos pull_owners)1d ago	23	\| GraphQL `artifactsEventsAdaptiveGroups` \| Artifacts' own count by `date`, `eventType` and `repositoryName`. Operations are `create`, `fork`, `push`, `pull`, `delete`; errors (`rateLimited`, `serverError`, …) are kept but not counted. \| `cost_lines`, source `artifacts_events`; per workspace (from the store key `<workspace>--<repo>`; a pull request's working copy, `pulls--<id>`, is its repository's workspace's, from repos' `pull_owners`) in `own_counts` as `cloudflare_git` \|
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	24	\| GraphQL `aiGatewayRequestsAdaptiveGroups`, filtered to `AI_GATEWAY_ID` \| What AI Gateway priced g1t's own provider traffic at, by `date`, `provider`, `model` and `wholesale`: `count`, `sum.cost` (dollars), `sum.tokensIn`/`tokensOut`/`cacheReadTokens`/`cacheWriteTokens`. Field names checked against Cloudflare's schema (introspection of `AccountAiGatewayRequestsAdaptiveGroups{Sum,Dimensions,Filter_InputObject}`). An adaptive (sampled) dataset: an estimate, close at g1t's volumes. Only g1t's hosted models go through this gateway: a workspace's own provider is called at its own address, never here. \| `cost_lines`, source `ai_gateway`, product `ai_gateway_requests`: per day and model a line `<provider>_<model>` (requests, at the gateway's cost), and at no cost `…__tokens`, `…__cache_read_tokens`, `…__cache_write_tokens`; Cloudflare-billed (unified billing) requests are prefixed `wholesale__`. Mapped to `models` (migration 0036). A re-read day replaces all its gateway lines. \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	25	\| The ledger \| Every charge: its cost at the price book's cost, what it was charged at price, what paid for it. \| read, never written \|
	26	\| `pending_usage` \| Month-end meters (git, storage, scans, embeddings, the cache) as they stand. \| snapshotted daily into `pending_days` \|
	27	\| `plan_payments` \| The plan's $20. \| read \|
One operation mapping, owned by repos; billing reads it instead of keeping its own2d ago	28	\| repos `git_operations` \| Operations customers are charged for, per workspace, counted by repos through its `operation_mapping`. \| `own_counts` meter `git_operations` \|
Costs: Cloudflare's subscriptions read from Cloudflare each day, the estimate only until then; sudo's costs split into Costs & margin and Bill & pricing1d ago	29	\| Subscriptions, `GET /accounts/{account}/subscriptions` \| What g1t pays each month whatever it uses (Workers Paid, add-ons): each subscription that is paid, trialing or awaiting payment, at its price over its frequency. Not on the billable-usage bill. Read in the daily run with the bill's token; a failure is logged and the last read stays. \| `cf_subscriptions` (one row) \|
One operation mapping, owned by repos; billing reads it instead of keeping its own2d ago	30	\| repos `artifacts_usage` \| Every raw meter of the git store (`git.fetch`, `git.receive_pack`, `binding.*`, …) per day and workspace, with repos' `operation_mapping`. \| `own_counts` meters `artifacts_<raw meter>`, and `cost_operations` (raw counts × the mapping's `cost_operations`: what g1t expects Cloudflare to bill) \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	31
	32	A meter's slug is Cloudflare's name lower-cased with words joined by `_`
	33	and the "(First … included)" note dropped: `Workers for Platforms CPU ms
	34	(First 60M ms are included)` under `Workers` is product `workers`, meter
	35	`workers_for_platforms_cpu_ms`. Several rows of the same day and meter
	36	(regions, tiers) are added together before they are stored.
	37
	38	## Credentials
	39
	40	\| Secret on g1t-billing \| Permissions \| Used for \|
	41	\| --- \| --- \| --- \|
Costs: Cloudflare's subscriptions read from Cloudflare each day, the estimate only until then; sudo's costs split into Costs & margin and Bill & pricing1d ago	42	\| `CLOUDFLARE_BILLING_TOKEN` (optional) \| Account: Billing Read, Account: Account Analytics Read, for the g1t account only \| Reading the bill, the Artifacts events and the subscriptions \|
Billing: AI Gateway's analytics are read with the token that can see them, and a gateway that priced nothing is said22h ago	43	\| `CLOUDFLARE_USAGE_TOKEN` (exists) \| Billing Read, Account Analytics Read, AI Gateway Read \| The keeper (settling runs from the gateway's logs); also the bill when `CLOUDFLARE_BILLING_TOKEN` is not set. AI Gateway's analytics are read with this token first and, if that is refused, with the bill's: Cloudflare answers a token without AI Gateway Read with no rows rather than an error, so the bill's token would read as a gateway that priced nothing \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	44
	45	With neither, the daily run reconciles only what g1t counted itself, and
	46	the page says the bill cannot be read. Nothing fails. To set the scoped one:
	47
	48	1. Cloudflare dashboard → My Profile → API Tokens → Create Token → Custom token.
	49	2. Permissions: Account · Billing · Read; Account · Account Analytics · Read.
	50	3. Account resources: Include · the g1t account. No zone permissions.
	51	4. `cd services/billing && npx wrangler secret put CLOUDFLARE_BILLING_TOKEN`.
sudo: the costs run button is named for what it does, the whole nightly analysis1d ago	52	5. In sudo, Costs & margin → Run the analysis now.
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	53
	54	Alerts are emailed through the `EMAIL` binding (Cloudflare Email Sending)
	55	to `COSTS_ALERT_EMAIL` (`hey@flagon.io`). An empty value sends none.
	56
	57	## Schedule
	58
	59	The daily cron (`17 4 * * *`, `keeper::DAILY`) runs, in order:
	60
	61	1. The keeper's measurements (sandbox seconds, app requests and CPU), each
	62	a proposal now, not a direct change.
	63	2. `costs_daily`:
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	64	1. Read the bill, the Artifacts events and AI Gateway's analytics. The first run reads the last
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	65	31 days (GraphQL keeps 31); later runs the last 4, since Cloudflare
	66	restates recent days, or back to the last day read after a gap.
	67	Lines are upserted on `(day, source, product, meter)`, so a re-read
	68	replaces, never adds.
	69	2. g1t's own counts for the same days (replaced per day).
	70	3. Snapshot `pending_usage` into `pending_days`.
sudo: the costs run button is named for what it does, the whole nightly analysis1d ago	71	4. Reconcile the last 31 days (further back after a gap) into
	72	`margin_days` and `workspace_costs`
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	73	(replaced per day).
	74	5. Drift over the last 7 days into `cost_drift`.
	75	6. Unit costs over the last 30 days, proposed to the price book.
	76	7. Apply price versions whose date has come.
	77	8. Open, update and close margin alerts; email new ones.
	78	9. Email owners on the plan about rises to come.
	79
Costs: Cloudflare's subscriptions read from Cloudflare each day, the estimate only until then; sudo's costs split into Costs & margin and Bill & pricing1d ago	80	Run the analysis now at the top of sudo's Costs & margin and Bill & pricing pages
sudo: the costs run button is named for what it does, the whole nightly analysis1d ago	81	(`admin_run_costs`) runs all of step 2 at once, alerts included, with no
	82	need to wait for 04:17 UTC. Running it twice is safe: every step replaces
	83	what it wrote.
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	84
	85	## Reconciliation math
	86
	87	Every Cloudflare line goes to one of g1t's products ("buckets") by
	88	`cost_map`: the row for its product with the longest matching meter
	89	prefix, `*` last. A line no row claims goes to `unmapped`.
	90
	91	\| Bucket \| Cloudflare \| Paid for by (`revenue_map`) \|
	92	\| --- \| --- \| --- \|
	93	\| `sandboxes` \| Containers, Durable Objects compute duration \| `sandbox`, `self_hosted`, `builds` \|
	94	\| `deployments` \| Workers for Platforms \| `deployments` \|
	95	\| `git` \| Artifacts operations (and its events, as counts) \| `git` \|
	96	\| `repo_storage` \| Artifacts storage \| `storage` \|
	97	\| `actions_cache` \| R2 \| `cache` \|
	98	\| `embeddings` \| Workers AI, Vectorize \| `context` \|
	99	\| `security` \| (Workers CPU, under `platform`) \| `security` \|
	100	\| `domains` \| Cloudflare for SaaS \| `domains` \|
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	101	\| `models` \| not Cloudflare: AI Gateway's settled cost on the ledger; AI Gateway's own daily total (`ai_gateway_requests`) beside it, to check it \| every other task (agent runs) \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	102	\| `platform` \| Workers, D1, KV, Queues, Email, Browser Rendering, other Durable Objects \| the plan's price \|
	103
	104	For each day and bucket:
	105
Costs: a statement that keeps usage sold, running g1t, subscriptions and what was given away (comped, free use, trial, pool) apart, and says who was paid; free use carries its own cost; the run button says it is running1d ago	106	- Cloudflare cost = Σ the bucket's lines' cost, as billed: after the
	107	included allowances, so a month inside them costs $0 here as on
	108	Cloudflare's Billable usage page. `models` uses the ledger's cost of the
	109	tokens instead; that is paid to the model providers and is not on
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	110	Cloudflare's bill. Its "Cloudflare" column is what AI Gateway priced the
	111	same traffic at, which drift compares with the ledger (below); it is
	112	never added to the cost.
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	113	- Own cost = Σ the ledger's `cost_micros` for the bucket's keys (the
	114	price book's cost when charged), plus month-end deltas. A workspace's own
	115	model provider is no cost to g1t.
	116	- Value = what customers were charged at price: `-amount_micros` plus
	117	what the plan's included usage, a trial, the open-source pool or g1t paid.
	118	g1t's own (comped) workspaces are valued at cost plus the margin.
	119	- Cash = what workspaces paid: `-amount_micros`, and the plan's price.
Merge Stripe Tax, the card fee on card payments, and one free workspace per person15h ago	120	Never tax or card fees: a payment credits the balance, and
	121	`plan_payments`, without them (see [Tax and the card fee](#tax-and-the-card-fee)).
Costs: margin is measured on what was sold; comped workspaces, free periods, the trial and the pools are given away, a budget shown beside it1d ago	122	- Given away = the part of the cost that went on usage g1t paid for
Costs: a statement that keeps usage sold, running g1t, subscriptions and what was given away (comped, free use, trial, pool) apart, and says who was paid; free use carries its own cost; the run button says it is running1d ago	123	itself on purpose, by why:
	124	- comped: all of a comped workspace's cost, every bucket;
	125	- free use: a free period's usage, the overruns g1t covered
	126	(`ledger.given_micros`), and all of a workspace's cost on a day it had
	127	nothing priced (free allowances);
	128	- trial and open-source pool: what `trial_micros` and
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	129	`oss_micros` paid;
	130	- discount: what a discount on an account's custom terms took below
	131	cost plus the margin (`ledger.discount_micros`, see
	132	[Margin floor](#margin-floor)). The usage is valued at its price, so a
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	133	discounted sale never reads as margin lost;
	134	- promotional credit and goodwill credit: what credit staff gave
	135	paid for, when it is spent (`given_credit_promotional_micros`,
	136	`given_credit_goodwill_micros`, migration 0038). That usage's charge is
	137	taken out of cash, so it is never money in. A refund is not here: see
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9713h ago	138	[Credits from g1t](#credits-from-g1t);
	139	- testing resets: what a workspace's usage cost g1t before staff
	140	reset its billing (`reset_costs`, `given_reset_micros`, migration
	141	0046). The model calls and Cloudflare usage still happened, so the
	142	reconciliation reads the kept rows back as that workspace's usage on
	143	their days: valued as before, no cash, all of it given. See
	144	[Resetting a test workspace](#resetting-a-test-workspace).
Costs: a statement that keeps usage sold, running g1t, subscriptions and what was given away (comped, free use, trial, pool) apart, and says who was paid; free use carries its own cost; the run button says it is running1d ago	145
	146	Otherwise a workspace's day is split by those shares of its value at
	147	price, and the same shares of each of its buckets' cost are given, its
	148	part of running g1t included. The Team plan's included usage is sold:
	149	the plan's price paid for it. Stored on `margin_days` (`given_micros`
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	150	and `given_<why>_micros`, `given_discount_micros` from migration 0036)
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9713h ago	151	and `workspace_costs` (`given_micros`). Sudo's Costs & margin page lists
	152	each why by name, testing resets included (`givenResetMicros`).
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	153	- Month-end meters: a day's figure is that day's `pending_days`
	154	snapshot less the day before's, within a month. Their month-end ledger
	155	entries are left out, so nothing is counted twice.
Costs: a statement that keeps usage sold, running g1t, subscriptions and what was given away (comped, free use, trial, pool) apart, and says who was paid; free use carries its own cost; the run button says it is running1d ago	156	- Product margin = (value − cost) / value.
	157	- Sudo's statement keeps apart:
	158	- Usage sold: cash for usage against the cost of the usage buckets
	159	less what was given. Its margin is the headline; at cost plus 20% it
	160	sits near 16.7%.
	161	- Running g1t: the plan's price against `platform` less its given
	162	share.
Costs: Cloudflare's subscriptions read from Cloudflare each day, the estimate only until then; sudo's costs split into Costs & margin and Bill & pricing1d ago	163	- Cloudflare subscriptions: what Cloudflare lists, a month, over
	164	the range (`cf_subscriptions`); until a read has worked,
	165	`CLOUDFLARE_FIXED_MONTHLY_MICROS`, an estimate.
Costs: a statement that keeps usage sold, running g1t, subscriptions and what was given away (comped, free use, trial, pool) apart, and says who was paid; free use carries its own cost; the run button says it is running1d ago	166	- Not mapped: billed, charged for by nothing.
	167	- Given away: by why. A budget, watched under g1t's own spend, never
	168	shown as a loss.
	169	- All in: money in against all of it, with the figure without what
	170	was given beside it. Who g1t paid splits the cost into Cloudflare
	171	and the model providers.
	172
	173	The overall alert is (Σ cash − (Σ cost − Σ given)) / Σ cash.
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	174	- Quantities: where a mapping names an `own_meter`, Cloudflare's
	175	billed quantity of those lines (or, without one, Artifacts' operation
	176	events) against g1t's own count.
	177
	178	Shared costs to workspaces. A bucket's cost is shared in proportion
	179	to, first available: Cloudflare's own per-workspace count
	180	(`cloudflare_<bucket>`, today the Artifacts events by repository), g1t's
Costs: a statement that keeps usage sold, running g1t, subscriptions and what was given away (comped, free use, trial, pool) apart, and says who was paid; free use carries its own cost; the run button says it is running1d ago	181	own count, what its usage cost (so free use carries its own cost), what
	182	each was charged for it. `platform`
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	183	and `unmapped` are shared by each workspace's share of all usage that
	184	day. Shares are whole micros that add up to the bill exactly (largest
	185	remainder).
	186
	187	## Drift (last 7 days)
	188
	189	\| Kind \| When \| What to do \|
	190	\| --- \| --- \| --- \|
One operation mapping, owned by repos; billing reads it instead of keeping its own2d ago	191	\| Count \| g1t's count and Cloudflare's differ by more than the mapping's `drift_percent` (10%) \| Find out what Cloudflare counts: compare its events with `own_counts` `artifacts_*` and `cost_operations`. If it counts more (binding reads, `ls-refs`), either change repos' `operation_mapping` so customers are charged for what Cloudflare counts, or leave it and let the per-unit cost rise (below). \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	192	\| Cost \| Cloudflare charged more than `drift_percent` away from the price book's cost of the same usage, with at least `min_daily_cost` \| A price is stale: check the proposals. \|
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9713h ago	193	\| Cost, on `models` \| What AI Gateway priced g1t's own provider traffic at over the 7 days, against the ledger's model cost for the same days (billed to g1t: comped, free and trial use included, a workspace's own provider not) plus the model cost testing resets kept for those days (`reset_costs`), more than the `ai_gateway_requests` mapping's `drift_percent` (10%) apart, with at least `min_daily_cost`. A ledger with none of the gateway's cost is drift too, and so is a gateway that priced nothing against a ledger with at least `min_daily_cost` of model cost (no percentage): that is not agreement, it is a token that cannot see AI Gateway, or calls that went around it \| The gateway higher: model calls g1t paid for and charged no one: runs not settled yet (they catch up within the hour), runs with no session, a run started without a billing ticket, or something else on g1t's gateway. The ledger higher: runs that reached a provider without the gateway. The detail adds why the gateway's own figure may be off: prompt-cache read and write tokens (the gateway prices them at its rates for cache tokens, which can lag the provider's; check against the provider's invoice), requests Cloudflare billed itself (unified billing: on Cloudflare's bill, not a provider's), and models with no price. A testing reset in the window is named in the detail: one that kept its cost says how much of the ledger's side it is; one from before resets kept their cost (the audit log has it, `reset_costs` does not) says the gateway's figure includes usage the ledger no longer has, so that part is not a leak, and the day it leaves the 7 days; while such a reset is in the window the `models` leak is not raised. Days are UTC by when a request ran (gateway) and when a charge was entered (ledger), so a run across midnight shifts a little between days; the 7-day sum absorbs it. \|
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	194	\| Unpriced \| Over the 7 days, a model in AI Gateway's analytics with tokens and $0 cost, or runs settled with `runs.gateway_note` (the gateway could not price all of a run) \| The gateway has no price for a model g1t runs: add it in the gateway (custom cost) or route away from it. Until then those runs are charged no less than the sandbox reported (Claude Code's own price table), never $0 silently. \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	195	\| Leak \| Cost of at least `min_daily_cost` and nothing charged for it (never for `platform`), or a meter in `unmapped` \| Map the meter (below), or decide it is overhead (`platform`). \|
	196
	197	## Prices: versions, proposals, notice
	198
	199	- `price_versions` holds every price ever, never edited. `prices` is the
	200	version in force. The daily run applies a version once its
	201	`effective_at` has come, and adds the public `price_changes` record.
	202	Ledger entries made from the price book carry `price_version` (the
	203	version ids, comma-separated), so a past statement is always explained
	204	by the prices of its day.
	205	- Proposals come from the keeper (sandbox seconds, app requests and CPU)
	206	and the reconciler (mappings with `scale_to_own`: today git operations).
	207	For git operations: Cloudflare's rate per its own operation (the median
	208	over charged days of cost ÷ quantity) × (Cloudflare's operations ÷ g1t's)
	209	× 1,000. If Cloudflare counts three for each one g1t counts, the per-1,000
	210	price triples. At least 1,000 of g1t's operations are needed.
	211	- Decision (`pricing::decide`): under 2% is noise; more than 4× either way
	212	is suspect and waits for staff; within `auto_apply_percent` (25%) it is
	213	applied on its own when `auto_apply` is on; anything else waits.
	214	- Notice: a fall applies at once. A rise applies `notice_days` (14) after
	215	the decision, and for a monthly meter (git, storage, cache, domains,
	216	embeddings, scans) at the start of the month after that, so no month
	217	is charged at two prices. Owners of workspaces on the plan are emailed
	218	once per rise (`price_notices`), and the pricing page lists it with
	219	"takes effect". Rises are never retroactive; margin protection is for
	220	new usage once notice has run.
	221	- Staff approve or reject in sudo. A rejection needs a note.
	222
	223	## Changing a mapping
	224
Costs: Cloudflare's subscriptions read from Cloudflare each day, the estimate only until then; sudo's costs split into Costs & margin and Bill & pricing1d ago	225	In sudo, Costs & margin → Bill & pricing → Mappings: Cloudflare's product and meter
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	226	prefix (as Cloudflare's lines lists them; `*` for the rest of the
	227	product), g1t's product, and optionally:
	228
	229	- Price meter: the price book meter the line measures.
	230	- Own meter: g1t's count of the same units (`own_counts.meter`).
	231	- Scale to g1t's count: price one of g1t's units at as many of
	232	Cloudflare's as it took (proposals as above).
	233	- Drift threshold.
	234
sudo: the costs run button is named for what it does, the whole nightly analysis1d ago	235	It applies from the next run; Run the analysis now applies it at once.
One operation mapping, owned by repos; billing reads it instead of keeping its own2d ago	236	Every change is in the audit log (`cost_mapping`).
	237
	238	## Which raw meters are operations
	239
	240	There is one mapping, and the repos service owns it: `operation_mapping`
	241	in g1t-repos' database, one row per raw meter with `cost_operations` (how
	242	many operations Cloudflare bills for it) and `billable_operations` (how
	243	many the customer is charged for). Change it with repos'
	244	`set_operation_mapping` RPC (services only), or
	245	`npx wrangler d1 execute g1t-repos --remote` until sudo has a form. A
	246	change applies to counts from then on, never to what was counted.
	247	Billing keeps no mapping of its own: it reads repos' `git_operations`
	248	(already mapped) for what customers are charged, and `artifacts_usage`
	249	(raw counts with the mapping) for `cost_operations`. Migration 0023 drops
	250	the `billable_units` table 0022 made for this, which was never written.
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	251
Models' margin read -14%: usage nothing paid for is valued at price, not $01d ago	252	Charged at price (a product's value) is what each day's usage was paid:
	253	charged to a card or credit, or drawn from the plan's included usage, a
	254	trial, a pool or a gift. Usage nothing paid for, as in a free period, is
	255	valued at price (cost plus the margin), since it was given away at its price
	256	rather than sold for nothing; so are g1t's own workspaces. Runs on a
	257	workspace's own model provider have no cost to g1t. Every daily run
	258	reconciles the whole 31-day window from what is already kept, so a change in
	259	how a day is valued reaches every day sudo shows.
	260
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	261	## Alerts runbook
	262
	263	\| Alert \| Raised when \| First steps \|
	264	\| --- \| --- \| --- \|
	265	\| Margin under the floor \| A product's value against cost under `margin_floor_percent` (10%) for `alert_days` (3) days running, each with at least `min_daily_cost` \| Open the product on Costs & margin. Cost up? Check proposals (approve a rise; it waits out the notice). Value down? A mapping or `revenue_map` may have moved. \|
Costs: margin is measured on what was sold; comped workspaces, free periods, the trial and the pools are given away, a budget shown beside it1d ago	266	\| All of g1t under the floor \| The same for money in against the cost of what was sold: every cost less what was given away (comped workspaces, free periods, the trial, the pools), which is a budget watched in budget.rs. While less than $1 a day comes in, it says the dollars, not a percentage \| Look at which products moved; check `platform` (it has no revenue of its own and grows with traffic). Before launch, with little paid usage, expect it. \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	267	\| Leak \| Drift of kind leak \| Map the meter, or decide it is overhead. \|
	268	\| Drift \| Count drift \| See Drift above. Cloudflare's definitions change in beta: ask them in writing ([ARTIFACTS.md](ARTIFACTS.md), §7). \|
Margin alerts measure what is sold, and say dollars when a percentage would mislead1d ago	269	\| Costs more than it pays \| A workspace's shared cost over 30 days above what its usage was priced at (`value_micros`, whoever paid: card, trial, gift or included usage) × `anomaly_factor`, at least `anomaly_floor`; not comped workspaces \| Shown on Reach out as "Costs more than it pays": its usage is priced below what it costs. Abuse (Abuse & fraud page) or a gap in pricing. Not emailed. A trial or gift paying for usage does not raise it. \|
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	270
	271	Alerts close on their own when the condition clears. Open ones are
	272	emailed again weekly. The red bar on every sudo page shows margin,
	273	overall and leak alerts.
	274
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	275	## Model costs
	276
	277	Every model call g1t pays for is an agent run's (the `claude` CLI in the
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens14h ago	278	sandbox, `crates/runner`) or a customer's AI Gateway request (a workspace
AI Gateway: OpenAI's format, open models, and your own providers13h ago	279	token with `models:write` at `models.g1t.sh/anthropic` or
	280	`models.g1t.sh/openai/v1`, `gateway.rs`, to Claude on Anthropic or to open
	281	models on Workers AI through the same AI Gateway); the only other model is
	282	Workers AI's embeddings for g1t's own search, which are on Cloudflare's bill
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens14h ago	283	(`embeddings`). How each reaches the ledger:
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	284
	285	\| Call \| Who pays \| Run and session \| Ledger cost \| Settled to the gateway \|
	286	\| --- \| --- \| --- \| --- \| --- \|
	287	\| Agent run through the model proxy (`services/models`) on g1t's hosted models \| g1t \| `runs` row; session `ms_…` in `cf-aig-metadata` \| On finish, the sandbox's figure (Claude Code's `total_cost_usd`, at its own price table, cache tokens included) \| Yes, every 15 minutes \|
	288	\| Agent run straight to the gateway (no `MODELS_URL`) \| g1t \| `runs` row; session `rs_…` in `cf-aig-metadata` (`services/runner` `gatewaySession`) \| As above \| Yes \|
	289	\| Agent run with no gateway (`AI_GATEWAY_ID` empty, self-hosting) \| g1t's key \| `runs` row, no session \| The sandbox's figure \| No: nothing to settle against \|
Merge branch 'model-routing'16h ago	290	\| Agent run on a workspace's own provider \| The workspace \| `runs` row, `billed_to = 'workspace'`, session `ms_…` (the proxy counts its tokens by it) \| No model cost (none to g1t); the agent rate on `agent_tokens_own`, line `<run>/agent-own` \| No; never on g1t's gateway. Closed by the cron's `settle_own_runs`, which charges tokens counted late \|
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9713h ago	291	\| AI Gateway request on g1t's key \| The workspace, from included usage and AI credit (`gateway_admit` refuses at $0, over the limit, or with no plan) \| No run; `gateway_requests` row; session `gw_<token>_<YYYYMMDDHH>` in `cf-aig-metadata` (`task: gateway`) \| Per request: its tokens at `gateway_models` (the table, migrations 0045 and 0047: list price per million by kind, five-minute and one-hour cache writes apart, and for a model priced by prompt length such as Claude Haiku 5.5 a `threshold` above which the whole request is at the `over_` prices) plus the `gateway_models` meter's markup (0 in beta); a `usage` line with task `gateway`, reference the request id, quantity 1 \| No, not yet: the session tag is there for it. Cost drift on `models` compares the gateway's total with these lines too. Requests billed other than by tokens (fast mode, `inference_geo`, fallbacks, server tools, containers) are refused by the proxy \|
AI Gateway: OpenAI's format, open models, and your own providers13h ago	292	\| AI Gateway request on a workspace's own provider (any model connection whose `gateway_models` takes the model) \| The workspace's provider \| `gateway_requests` row, `own_key = 1`, `provider` and `connection` \| None \| No; never on g1t's gateway \|
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	293	\| A sandbox that died before reporting \| g1t \| as its route \| Charged from the gateway when settled \| Yes \|
	294	\| Embeddings (indexing) \| g1t \| none (Workers AI) \| Month-end `context` meter \| No: Cloudflare's bill, `embeddings` bucket \|
	295	\| Embeddings (queries, search and agent context) \| g1t \| none \| None: not charged, by design \| No: in Cloudflare's `embeddings` line, shared out \|
	296
	297	Settling. A run's charge is corrected to what AI Gateway priced its
	298	session's requests at (`settled_cost` in `keeper.rs`). The gateway's
	299	figure is trusted in full: it is not held to the $100 cap on a sandbox's
	300	own report. It is never taken below what the sandbox reported when it
	301	cannot be the whole cost: a request with tokens and no cost (a model the
	302	gateway has no price for) or more logs than are read (2,000). Such a run
	303	keeps `runs.gateway_note`, its correction says why, and it raises the
Merge the AI Gateway: Anthropic's Messages API on a workspace's tokens14h ago	304	Unpriced drift. For agent runs g1t keeps no token rates of its own:
	305	the first figure is Claude Code's, the final one the gateway's. AI Gateway
Models: g1t keeps up with new models, and staff choose each default in sudo11h ago	306	requests are the exception: they are charged from `gateway_models` (the
	307	model catalogue, below), which has to follow the provider's price list by
AI Gateway: OpenAI's format, open models, and your own providers13h ago	308	hand until they are settled like runs. It is not part of the price book's
Models: g1t keeps up with new models, and staff choose each default in sudo11h ago	309	`price_versions`: a new model's prices are confirmed when staff approve it
	310	in sudo, and a changed price on a model already offered is a migration that
	311	updates the row and its `updated_at` (as 0047 did for Sonnet 5.5's cache
	312	reads). The `gateway_models` meter's markup is the only price-book number
	313	on it. Open
AI Gateway: OpenAI's format, open models, and your own providers13h ago	314	models need `WORKERS_AI_TOKEN` (a Cloudflare API token with Workers AI on
	315	g1t's account) on the model proxy; without it, and without
	316	`AI_GATEWAY_TOKEN` holding that permission, they are refused with `503`.
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	317
	318	The daily total. AI Gateway's analytics for the day (above) against
	319	the ledger's model cost is the check that nothing slips past: a model call
	320	with no run, or a run never settled, shows as Cost drift on `models`.
	321	The gateway's per-request `cost` is its estimate from its own price list:
	322	it can be off for prompt-cache tokens, for requests Cloudflare bills
	323	itself, and for models it has no price for. The drift's detail says when
	324	any of those were in the window; the provider's invoice is the last word.
	325
	326	### Margin floor
	327
	328	A sold charge is cost × (1 + `MARGIN_PERCENT`), rounded up (`margin_on`;
	329	`charge_micros` for a sandbox's own report). Terms change it only as
	330	follows (`Terms::discounted`, `Billing::charged`):
	331
	332	- Standard: charged in full.
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	333	- A 100% discount (what was "comped"; see [Discounts](#discounts)),
	334	`FREE_WHILE_BUILDING`, the plan's included usage, the trial,
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	335	the open-source pool, and overruns g1t covers: given, and counted by why
	336	(above).
	337	- Custom, with a discount: the discount comes off, and what it took
	338	below cost plus the margin is written on the entry as
	339	`ledger.discount_micros` and counted as given (discount), so the sale
	340	is valued at its price and charged plus given is never under cost plus the
	341	margin. On a settlement correction it moves with the charge (less than
	342	nothing when the charge comes down).
	343	- Goodwill credits (overages) are separate, given by staff on purpose:
	344	their margin part first, the cost only up to the cap, each audited.
	345
	346	Every usage path goes through this: `finish_run`, settling, sandbox time,
	347	features and builds (`charge_feature`), and the month-end meters.
	348
Models: g1t keeps up with new models, and staff choose each default in sudo11h ago	349	## The model catalogue
	350
	351	Every model g1t can use is one row of `gateway_models` (migrations 0045,
	352	0047 and `0048_model_catalogue.sql`; code in `catalogue.rs`): the agents'
	353	tiers, the AI Gateway's Claude and open models, and the embeddings model.
	354	Billing keeps it because billing owns prices: the gateway charges from the
	355	same row, so there is one price per model, not two that drift. Page: sudo
	356	Agents & models (`/agents`).
	357
	358	\| Column \| What \|
	359	\| --- \| --- \|
	360	\| `model`, `name`, `provider`, `kind` \| The provider's id, the name people see, `anthropic` or `workers-ai`, `chat` or `embeddings` \|
	361	\| `aliases` \| Other ids the provider lists it by, comma separated (a dated id such as `claude-haiku-4-5-20251001`) \|
	362	\| `family`, `tier_hint` \| `haiku`, `sonnet`, `opus`, `fable` (or a Workers AI author); the agent tier it suits: `small`, `large`, `frontier` \|
	363	\| `context_window`, `max_output`, `capabilities`, `dimensions` \| From the provider's list where it gives them: `effort`, `thinking`, `tools`, `vision`, `embeddings`; an embeddings model's vector length \|
	364	\| Prices \| Per million tokens in millionths: input, output, cache read, five-minute and hour-long cache writes, and for a model priced by prompt length the `threshold` and `over_` prices \|
	365	\| `status` \| `available` (routed to and offered), `new` (found, not approved), `deprecated` (the provider stopped listing it), `retired` (staff took it out) \|
	366	\| `priced` \| 1 when its prices are known \|
	367	\| `source`, `first_seen_at`, `last_seen_at`, `missing_since`, `approved_by`, `approved_at`, `note` \| Where it came from (`discovered` or `staff`) and its history \|
	368
	369	What each status allows:
	370
	371	\| Status \| Default for a purpose \| Offered on the AI Gateway \| Charged \|
	372	\| --- \| --- \| --- \| --- \|
	373	\| `available`, priced \| Yes \| Yes \| Yes \|
	374	\| `new`, or unpriced \| No \| No: refused before it reaches a provider \| No \|
	375	\| `deprecated` \| No: a default that chose it falls back \| Yes, to whoever names it \| Yes \|
	376	\| `retired` \| No: a default that chose it falls back \| No \| No \|
	377
	378	### Discovery
	379
	380	The models service lists each provider once a day (`29 5 * * *`, after
	381	billing's daily run) and whenever staff press Check for new models
	382	(`services/models/src/discover.ts`, through its `Discovery` entrypoint,
	383	which only sudo binds). Listing models is free; nothing calls a model.
	384
	385	\| Provider \| How it is listed \| Credentials (on g1t-models) \|
	386	\| --- \| --- \| --- \|
	387	\| Anthropic \| `GET /v1/models` through g1t's AI Gateway (`…/anthropic/v1/models`, tagged `task: discovery`), or straight to Anthropic with g1t's key when there is no gateway \| `AI_GATEWAY_TOKEN` (the gateway holds Anthropic's key), or `ANTHROPIC_API_KEY` \|
	388	\| Workers AI \| `GET /accounts/{account}/ai/models/search` \| `WORKERS_AI_TOKEN` (Workers AI Read), else `AI_GATEWAY_TOKEN` \|
	389
	390	Each provider's list goes to billing's `record_discovery`, which compares
	391	it with the catalogue:
	392
	393	- An id it has never seen is added as `new`. Chat and embeddings
	394	models only. Anthropic models are priced from the price table in
	395	`catalogue.rs` (`ANTHROPIC_PRICES`: Anthropic's list prices by model, a
	396	dated id priced as its model) when it has them; Workers AI models from
	397	the price their listing gives, with cached tokens at the input price.
	398	Anything else is added unpriced. Its family and tier hint come from its
	399	id (`claude-haiku-` is fast, `claude-sonnet-` standard,
	400	`claude-opus-` and `claude-fable-` most capable).
	401	- A dated id of a model it has (`claude-sonnet-5-5-20261001`) is that
	402	model: the id is added to its aliases.
	403	- A model it has that is listed gets `last_seen_at`, and its context
	404	window, output limit and capabilities from the list.
	405	- A model it has that is not listed (available or new) becomes
	406	`deprecated`, with `missing_since`. Listed again, it goes back to
	407	`available` if it was ever approved, else to `new`.
	408	- An empty list or a failed one changes nothing: it is recorded as a
	409	failed check with the provider's answer (never a key).
	410
	411	Every check is kept 90 days in `model_checks` and shown on the page. When a
	412	check adds, deprecates or restores anything, it is in the audit log
	413	(`models_discovered`, as `schedule` or the staff member) and staff are
	414	emailed at `COSTS_ALERT_EMAIL` with a link to Agents & models.
	415
	416	When Anthropic publishes a new model's price, add a row to
	417	`ANTHROPIC_PRICES`, so the next one of its kind arrives priced. Until then
	418	staff enter the prices when they approve it.
	419
	420	### Approving, retiring and restoring
	421
	422	On Agents & models, New models lists every `new` model with its prices
	423	filled in where they are known. To approve one:
	424
	425	1. Check the name people see and the tier it suits.
	426	2. Check or enter its prices per million tokens against the provider's
	427	price page: input, output, cache read, cache writes (five-minute and
	428	hour-long; an hour-long price left empty is the five-minute one), and
	429	under Priced by prompt length the threshold and the prices above it.
	430	3. Say why (for example where the prices came from), and Approve
	431	(`admin_decide_model`, `approve`).
	432
	433	It is `available` at once: the AI Gateway offers it within five minutes
	434	(the proxy keeps the catalogue that long) and it can be chosen as a
	435	default. Retire takes a model out of routing and the gateway; any
	436	default that chose it falls back to the next suitable model until staff
	437	choose another, and the audit line names those defaults. Restore puts
	438	a retired or deprecated model back: `available` if it was ever approved,
	439	else `new`. Each needs a reason and is in the audit log (`model_approved`,
	440	`model_retired`, `model_restored`).
	441
	442	### Defaults
	443
	444	`model_defaults` holds staff's choice per purpose, each with when, who and
	445	why (`admin_set_model_default`; the audit log, `model_default`, has the old
	446	value, the new one and why):
	447
	448	\| Purpose \| What it chooses \| Read by \|
	449	\| --- \| --- \| --- \|
	450	\| `tier_small`, `tier_large`, `tier_frontier` \| The model behind Auto's fast, standard and most capable tiers \| The runner \|
	451	\| `background` \| The harness's own small tasks in every run on g1t's tiers (`ANTHROPIC_SMALL_FAST_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`) \| The runner \|
	452	\| `gateway_first` \| The Claude listed first by `GET /openai/v1/models` \| Billing's `gateway_models` \|
	453	\| `job_implement`, `job_revise`, `job_answer`, `job_review`, `job_update`, `job_plan` \| Each kind of job's starting tier (`small`, `large`, `frontier`; a review also `change`, sized by its change) and effort (`low` to `max`, or none for the harness's own) \| The runner \|
	454
	455	A model purpose takes only an available, priced Claude chat model (the
	456	harness speaks Anthropic's API). The migration seeded each with what
	457	`AGENT_ROUTING` had.
	458
	459	Before a default is saved, sudo shows it beside the current one with what
	460	a typical run would cost on each: 40 requests of 2,000 input, 1,500
	461	output, 45,000 cache-read and 4,000 cache-write tokens, each request priced
	462	on its own at the catalogue's prices (`catalogue::TYPICAL`; on 2026-10-08,
	463	$0.076 on Claude Haiku 5.5, $1.34 on Sonnet 5.5, $2.68 on Opus 5.5). It is
	464	an estimate for comparing models, never a charge.
	465
	466	How the runner reads them. `model_defaults` (the RPC) returns each
	467	purpose's model as it applies now, with its prices and capabilities, and
	468	each job's tier and effort. The runner reads it at most once a minute per
	469	isolate and puts it over `AGENT_ROUTING` (`withDefaults` in
	470	`services/runner/src/model-env.ts`), so a change reaches runs within a
	471	minute. When billing cannot be read, the runner uses `AGENT_ROUTING` (and
	472	`DEFAULT_ROUTING` under it) alone and asks again ten seconds later. The
	473	labels, change sizes, `frontierAfter` and learning always come from
	474	`AGENT_ROUTING`. Effort is not sent on a model whose catalogue entry lacks
	475	`effort` (Claude Haiku 4.5).
	476
	477	Never a retired model. A chosen model that is deprecated, retired or
	478	unpriced is not handed out: the purpose falls back to the first available,
	479	priced Claude with the same tier hint (any Claude for `gateway_first`), in
	480	the catalogue's order, with a sentence such as *Claude Haiku 5.5 is
	481	retired; using Claude Haiku 4.5 instead.* The runner adds that sentence to
	482	the run's reason line, and sudo shows it beside the default. With no model
	483	left for a purpose, the runner keeps `AGENT_ROUTING`'s.
	484
	485	Not a default: the context hub's embeddings model
	486	(`@cf/baai/bge-base-en-v1.5`, in `services/context`). Its vectors are
	487	only comparable with others from the same model, so changing it means a
	488	new index, rebuilt; it is pinned in code, and listed in the catalogue with
	489	its price. No other g1t service calls a model.
	490
	491	Customers never choose among these: they keep Auto, or pin a tier per
	492	kind of work, and nothing customer-facing names the catalogue.
	493
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	494	## Discounts
	495
	496	An account's terms are standard, or custom: a discount from 1 to 100%,
	497	a limit of its own, or both, with a reason (the terms' note) and an
	498	optional end date. What used to be "comped" is a 100% discount
	499	(`Terms::full_discount`; migration `0039_discounts_not_comped.sql` moved
	500	every `comped` row to `custom` at 100%, and code reads a leftover `comped`
	501	row as 100%). In SQL, `sales::FULL_DISCOUNT_SQL`.
	502
	503	- Charging. Every charge records what the discount took off it
	504	(`ledger.discount_micros`), 100% included: the entry is charged nothing
	505	and the discount is its whole price. Migration 0039 backfilled the
	506	discount on a 100%-discounted workspace's earlier entries that were
	507	charged nothing and paid by nothing, at cost plus 20%.
	508	- What a 100% discount still does as "comped" did. The plan is on
	509	without its price (`PlanKind::Internal`), trust is `internal` (no limit
	510	on unpaid usage), nothing is invoiced or closed, and g1t's own spend on
	511	it is held to the monthly budget (the terms' limit, at cost; see
	512	[Spend caps](#spend-caps)).
	513	- The statement and Usage. The customer sees every usage line at its
	514	price (`StatementLine.price_micros`: charged, plus what paid for it, plus
	515	the discount), the discount per day or project and in the totals
	516	(`StatementTotals.price_micros`, `discount_micros`, `discount_percent`),
	517	and the CSV has price and discount columns. The Usage page measures at
	518	price for a discounted account (`Usage.discount_micros`,
	519	`discount_percent`).
	520	- Margin. A 100% discount's usage is given away as before, in the
	521	bucket still named `comped` (`given_comped_micros`); sudo calls it
	522	100% discounts. A partial discount's part below cost plus the margin
	523	is `given_discount_micros` (partial discounts). Both are kept apart
	524	from margin on what was sold.
	525	- sudo. The workspace's Terms form takes a discount (None, 25%,
	526	50%, 100%, or Custom, a whole percent; the custom field shows by CSS
	527	alone), a limit, an end date and the reason. Badges and filters say
	528	100% discount or N% off. Each change is audited (`terms`), such as
	529	`standard → 100% discount, monthly budget $150.00: g1t's own`.
	530
	531	## Credits from g1t
	532
	533	Staff give a workspace credit from sudo; the code is
	534	`services/billing/src/grants.rs`, the tables `credit_grants` and
	535	`ledger.credit_kind` (migration `0038_staff_credits.sql`).
	536
	537	### Giving credit
	538
	539	sudo → the workspace (or an enterprise, choosing one of its workspaces) →
	540	Give credit:
	541
	542	1. Amount: $10, $20, $25, $50, $100, or Custom (up to $10,000).
	543	Up to $100 it is one step; over $100, type the workspace's slug as well.
	544	2. Kind: promotional (a welcome, a referral, an event), goodwill (an
	545	apology), or refund (money back for something that went wrong: say what
	546	it refunds and, optionally, the day).
	547	3. Expires: never, 30, 90 or 365 days, or the end of a chosen day
	548	(UTC). A refund never expires.
	549	4. Note: required. It is on the statement and in the owners' email.
	550
	551	The form needs no JavaScript: the fields for one choice (the custom amount,
	552	a refund's details, the expiry date) show by CSS alone, and all show where
	553	`:has()` is not supported. `admin_credit` checks everything again.
	554
	555	A grant is a `crd_…` ledger line (kind `top_up`, so never a payment) with
	556	`credit_kind`, and a `credit_grants` row. The balance rises at once. The
	557	owners are emailed through identity's `notify_owners` (the same path as
	558	limit notices). It is audited as `credit`. The Overages queue's one-click
	559	goodwill credit is a grant too, of kind goodwill.
	560
	561	The inbox is not told: its items are threads on a repository, built from
	562	events, and a credit is a workspace's. That needs a workspace-level inbox
	563	thread first.
	564
	565	### How it is spent
	566
	567	Credit is spent before anything prepaid, the soonest-expiring grant first
	568	(never-expiring last, then the oldest). Given while the workspace owes, it
	569	pays what is owed first, the most recent usage first. What each grant paid
	570	for is never stored: `grants::replay` works it out from the ledger in order,
	571	so the charge paths do not know about credit and the answer is always what
	572	the ledger says. A charge that comes down (a settled run) gives back to
	573	the grant that paid last, while it can still be spent.
	574
	575	### Expiry and revoking
	576
	577	- Expiry. The daily run (`expire_credits`, before the reconciliation)
	578	closes grants past `expires_at` and enters what was left as a negative
	579	`crd…_expired` line; audited as `credit_expired`. A grant past its expiry
	580	pays for nothing even before the run.
	581	- Revoke. sudo → the workspace's Credits (or Credits & refunds)
	582	→ Revoke unused, with why (`admin_revoke_credit`): what is left, as a
	583	`crd…_revoked` line, audited as `credit_revoked`. What was spent stays
	584	spent.
	585
	586	Neither takes the balance below zero: at most the balance, if a refunded
	587	payment left less there than the credit.
	588
	589	### How margin treats them
	590
	591	\| Kind \| When spent \| On the day it was given \|
	592	\| --- \| --- \| --- \|
	593	\| Promotional \| The usage is valued at its price, its charge comes out of cash and is given (`given_credit_promotional_micros`) \| Nothing \|
	594	\| Goodwill \| The same, as `given_credit_goodwill_micros` \| Nothing \|
	595	\| Refund \| Paid for: cash, as any usage \| Its amount (less what was revoked) comes off cash on the day it refunds, shared over that day's paid usage \|
	596
	597	A refund gives back money already collected, so counting it as given would
	598	make it look like a budget g1t chose to spend. Taking it off cash for the
	599	day it refunds says that day's sale was worth less, and counting what it
	600	later pays for as cash keeps money in equal to what was collected. The
	601	refund's day is clamped to the last 30 days, the days the reconciliation
	602	recomputes; an older one lands on the oldest. Refunds never expire, so
	603	cash taken back is never stranded.
	604
	605	What credit paid of a month-end meter (storage, git, scans) is its own
	606	row on the day it was charged, since those meters are reconciled from
	607	snapshots. Sudo's Costs & margin lists promotional and goodwill credit
	608	under Given away, and below the statement the range's credits given,
	609	spent, and refunded. Credits & refunds (`/credits`, `admin_credits`)
	610	lists every grant (by kind, month, staff and workspace) and the last 12
	611	months by kind: given, spent, expired, revoked.
	612
Usage, Billing settings and prepaid AI credit; fixes from the UX audit16h ago	613	### Purchased and scoped credit (prepaid AI)
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	614
Usage, Billing settings and prepaid AI credit; fixes from the UX audit16h ago	615	`credit_grants` also has `scope` (`all`, or `models`: model usage only,
	616	`grants::is_model_usage`, which includes the agent rate) and `source`
	617	(`staff`, `purchase`, `promo_code`, `upgrade`), and `CreditKind::Purchased`.
	618	Spending takes credit scoped to models first, then the soonest-expiring. A
	619	grant scoped to models given while the workspace owes pays only what models
	620	owed, never other usage (`replay`). Purchased credit is money paid in: its
	621	ledger line is a payment (Stripe's id, never `crd…`, `credit_kind`
	622	`purchased`, statement kind AI credit), and the usage it pays for stays
	623	money in, never given. Staff cannot give it (`admin_credit` refuses the
	624	kind). Code: `services/billing/src/ai.rs`; migration `0040_ai_credit.sql`.
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	625
Usage, Billing settings and prepaid AI credit; fixes from the UX audit16h ago	626	- Buying. `buy_ai_credit` opens Stripe Checkout (payment mode, $10 to
	627	$1,000, a second line Card processing fee when the `card_fee` cost
	628	setting is on, `setup_future_usage=off_session`), recorded in `checkouts`
	629	with `feature = 'ai_credit'`, `amount_cents` the credit and `fee_cents`
	630	the fee. The credit is entered by whichever comes first, the person coming
	631	back (`confirm_ai_credit`, `?ai_credit=cs_…`) or
	632	`checkout.session.completed`: both claim the row `open → paid`, the
	633	grant's id is the session's id (`INSERT OR IGNORE`) and the ledger's
	634	reference is unique, so a payment is credited exactly once. Expires 365
	635	days after purchase (the daily `expire_credits`).
	636	- Owed. AI credit props up the balance but is money only for models, so
	637	what is owed is `max(0, AI credit left − balance)` (`owed_with`; at a
	638	month's close, `models_left_before` the month's start).
	639	- Auto-reload. `ai_reload` (settings; off by default) and `ai_reloads`
	640	(one row per attempt). Each cron run (and a run that would be refused)
	641	calls `reload_now`: below the threshold, it charges the customer's default
	642	payment method off-session for the target less the balance (whole
	643	dollars, at least $10, within the month's maximum), with the idempotency
	644	key `reload/<workspace>/<YYYY-MM>/<n>` (a retry after a crash is the same
	645	PaymentIntent), and grants purchased credit with the PaymentIntent's id. A
	646	decline or a payment needing the person turns auto-reload off
	647	(`failed_at`, `error`), emails the owners and audits `ai_reload_failed`.
	648	- At $0. `start_run` on g1t's models refuses with `payment_required`
	649	when the workspace is on the paid plan (not a 100% discount, not an
	650	enterprise), its included usage is used, and AI credit is $0 or less.
	651	- Upgrade credit. The first time a plan subscription is recorded active
	652	(`features::record`), $5 of promotional credit scoped to models, id
	653	`crd_upgrade_<workspace>`, expiring in a year: given, never revenue. Never
	654	for a workspace with a 100% discount.
	655
	656	### The agent rate and models' markup
	657
	658	Price-book meters (migration 0040, each with versions and a public change):
	659	`agent_models` (per provider dollar; markup 20% until 2026-10-08, then 0,
	660	a fall applied at once), `agent_tokens` ($0 until 2026-10-22, then $0.25 a
	661	million tokens: a rise, after the 14 days' notice, emailed to owners on the
	662	plan by `tell_owners_of_rises`), `gateway_models` (markup 0 during beta),
	663	`card_fee_percent` (29,000 micros per dollar) and `card_fee_fixed`
	664	(300,000). Changing any is a price-book change, never a deploy. `finish_run`
	665	and `settle` charge models at `agent_models`' markup; `charge_agent_rate`
Merge branch 'model-routing'16h ago	666	charges the weighted tokens of the run's session since it was last charged
	667	(`runs.agent_tokens`, the weighted tokens charged so far, claimed with a
	668	compare-and-set), on a line `<run>/agent` (later `<run>/agent/<tokens>`),
	669	with `quantity` the weighted tokens. What it counts is the more of what
	670	`token_usage` holds for the session and what the sandbox reported with its
	671	cost (`finish_run`'s `tokens`, from Claude Code's closing `usage`), each
	672	weighted by kind. Card fee switch: sudo → Costs → Guardrails → *Card fee
Merge Stripe Tax, the card fee on card payments, and one free workspace per person15h ago	673	on card payments* (`cost_settings.card_fee`, `on`/`off`, on by default). It
	674	covers every card payment now, not only AI credit: see
	675	[Tax and the card fee](#tax-and-the-card-fee).
Usage, Billing settings and prepaid AI credit; fixes from the UX audit16h ago	676
Merge branch 'model-routing'16h ago	677	On a workspace's own model key (migration `0041_agent_rate_own_key.sql`):
	678	the run keeps its model session (`runs.session_id`, `ms_…`) so the proxy's
	679	counts reach it, and the agent rate is charged at `agent_tokens_own` ($0 until
	680	2026-10-22, then $0.25 a million, a rise from nothing with its notice), on
	681	`<run>/agent-own` (later `<run>/agent-own/<tokens>`), `billed_to = 'g1t'`
	682	(g1t's own charge: it counts toward limits and spend), named *Agent rate,
	683	your own model key* on Usage and the statement. The model is never charged.
	684	`settle_runs` skips these runs (nothing on g1t's gateway); the cron's
	685	`settle_own_runs` closes them 5 minutes after they finish (3 hours after
	686	they start, for a sandbox that never reported) and charges tokens counted
	687	late. Runs from before have no session and are never charged the rate.
	688
	689	### The agent rate's token weights
	690
	691	How much each kind of token counts toward the agent rate, on g1t's models
	692	and own keys alike, is four price-book meters (migration
	693	`0042_agent_rate_weights.sql`): `agent_token_weight_input`, `_output`,
	694	`_cache_read` and `_cache_write`, each a weight in millionths in
Billing: cache reads count a tenth toward the agent rate15h ago	695	`cost_micros` (1,000,000 counts a token once). They started at 1, which is
	696	what the rate always counted; since 2026-10-08 cache reads count a tenth
	697	(100,000; migration `0044_cache_reads_count_a_tenth.sql`), as model providers
	698	price them. Input, output and cache writes count once. A cached agent run reads most of its context from
Merge branch 'model-routing'16h ago	699	cache (about 90% of its tokens on a typical Sonnet implement run), so the
	700	cache-read weight is the lever: at 1 the rate adds about 44% to such a run's
	701	model cost; at 0.1, far less.
	702
Billing: cache reads count a tenth toward the agent rate15h ago	703	To change a weight (cache reads went to a tenth this way):
Merge branch 'model-routing'16h ago	704
	705	1. Add the version, effective at once (a lower weight is a fall):
	706
	707	```sql
	708	INSERT INTO price_versions (id, meter, version, cost_micros, markup_percent, effective_at, reason, created_by, created_at)
	709	VALUES ('pv_agent_token_weight_cache_read_2', 'agent_token_weight_cache_read', 2, 100000, 0,
	710	'2026-10-08T00:00:00Z', 'Cache reads count a tenth toward the agent rate', 'staff', '2026-10-08T00:00:00Z');
	711	```
	712
	713	in a migration, or with `npx wrangler d1 execute g1t-billing --remote`
	714	until sudo has a form.
	715	2. The daily run applies it once `effective_at` has come and writes the
	716	public `price_changes` record (Run the analysis now applies it at
	717	once). Raising a weight later is a rise: give it an `effective_at` 14
	718	days out, and owners on the plan are emailed.
	719	3. Check `/pricing`: the agent rate's row lists the weights, and Usage's
	720	agent-rate lines name them.
	721
	722	`weighted` (`ai.rs`) rounds down to a whole token; a weight is never below 0.
	723
Usage, Billing settings and prepaid AI credit; fixes from the UX audit16h ago	724	### Budgets
	725
	726	The owners' spend limit is the budget. `limits.alert_levels` (comma
	727	separated, default every level), `limits.pause_at_limit` (default 1; off,
	728	100% is a warning, never a stop; the trust ceiling still stops work) and
	729	`limits.budget_webhook` (an https address, not g1t's; posted once per alert
	730	level a month by `warn_limits`). `set_budget` sets them, with `keepLimit`
	731	to leave the limit itself alone. A free workspace (trust `new`) has no
	732	spend limit to set: `set_spend_limit` and `set_budget` say so.
	733
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	734	### Earlier credits
	735
	736	Migration 0038 makes every earlier `Credit from g1t:` line a goodwill
	737	grant with no expiry: the old form asked for "a refund or goodwill" with
	738	no way to tell them apart, and goodwill never reads as money in.
	739
Mission control shows model usage, yours and the workspace's: tokens, cost, active days, cache share, each day, and the mix1d ago	740	## Token usage
	741
	742	The model proxy (`services/models`) reads Anthropic's `usage` from every
	743	`/v1/messages` answer, streamed or whole, on g1t's models and on a
	744	workspace's own provider alike (OpenAI-shaped providers are translated
	745	first). Count-tokens requests are not answers and are skipped. After the
	746	answer, it calls `record_tokens`, which adds input, output, cache reads and
	747	cache writes to one row per day, workspace, person, session and model in
	748	`token_usage` (migration `0030_token_usage.sql`). The person is who the run
	749	was for, from the model session's `requested_by`; never g1t's agent. A
	750	report that fails is dropped and never affects the answer.
	751
	752	`token_usage` reads a window (42 days by default, 366 at most) for the
	753	workspace or one person: totals, every day's tokens and the active days,
	754	with `costMicros` the window's run charges from the ledger, measured as
Merge branch 'model-routing'16h ago	755	`usage` measures them. Usage's report also lists tokens by model
	756	(`UsageReport.models`). The agent rate is charged on these counts (above);
	757	a run's model is still priced from AI Gateway's logs, never from them.
Mission control shows model usage, yours and the workspace's: tokens, cost, active days, cache share, each day, and the mix1d ago	758
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	759	## Tables (migration `0022_costs_and_margin.sql`)
	760
One operation mapping, owned by repos; billing reads it instead of keeping its own2d ago	761	`cost_lines`, `cost_map`, `revenue_map`, `own_counts`,
Git storage hardened, pages in tens of milliseconds, honest security alerts, and costs reconciled daily2d ago	762	`pending_days`, `margin_days`, `workspace_costs`, `cost_drift`,
	763	`margin_alerts`, `price_versions` (seeded with every current price as
	764	version 1), `price_proposals`, `price_notices`, `cost_settings` (the
	765	guardrails, seeded), the `actions_cache` price, and `ledger.price_version`.
	766	Every create is `IF NOT EXISTS` and every seed `INSERT OR IGNORE`; the one
One operation mapping, owned by repos; billing reads it instead of keeping its own2d ago	767	`ALTER` is applied once by D1's migration tracking. Migration
	768	`0023_one_operation_mapping.sql` drops `billable_units` (see above).
Merge branch 'worktree-agent-a633ac0f7f66d419d'1d ago	769	Migration `0036_model_costs_in_full.sql` adds `ledger.discount_micros`,
	770	`margin_days.given_discount_micros`, `runs.gateway_note` and the
Billing: credits with a kind and expiry, discounts instead of comped, and safer charging16h ago	771	`ai_gateway_requests` → `models` mapping. Migration
	772	`0038_staff_credits.sql` adds `credit_grants`, `ledger.credit_kind` and
	773	`margin_days.given_credit_{promotional,goodwill}_micros`, and backfills
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9713h ago	774	earlier credits (see [Credits from g1t](#credits-from-g1t)). Migration
	775	`0046_reset_costs.sql` adds `reset_costs` and `margin_days.given_reset_micros`
	776	(see [Resetting a test workspace](#resetting-a-test-workspace)).
Spend caps: a monthly budget for comped workspaces and a daily breaker on what g1t pays2d ago	777
	778	## Spend caps
	779
	780	Two caps keep what g1t pays for itself bounded while billing takes no
	781	real money. Both are measured at cost (what Cloudflare and the model
	782	providers charge g1t), never at price. Code: `services/billing/src/budget.rs`.
	783	Page: sudo Costs & margin → g1t's own spend (`/costs#spend`).
	784
	785	### What counts as g1t's own spend
	786
	787	Every charge that settles (an agent run's model cost from `finish_run` or
	788	AI Gateway's settlement, sandbox time from `record_sandbox`, a build from
	789	`charge_feature`) is split by what paid for it and g1t's part is added to
	790	`g1t_spend` (day, bucket, billing account):
	791
	792	\| Bucket \| What \|
	793	\| --- \| --- \|
	794	\| `comped` \| All of a comped account's work (flagon-io) \|
	795	\| `trial` \| The trial credit's share \|
	796	\| `oss` \| The open-source pool's share \|
	797	\| `given` \| A free workspace's overrun past its last bit of trial \|
	798	\| `unpaid` \| Charged, but with no real money behind it: Stripe's test key, or `FREE_WHILE_BUILDING` \|
	799
	800	The plan's included usage and on-demand charges count as revenue only
	801	with live payments; in test mode they are `unpaid`. A workspace's own
	802	model provider costs g1t nothing and is not counted. Month-end meters
	803	(git, storage, scans, embeddings, the cache) are not counted here; the
	804	daily reconciliation covers them. Migration `0024_spend_caps.sql`
	805	backfills the current month from the ledger.
	806
	807	### Caps
	808
	809	\| Cap \| Variable (g1t-billing) \| Default \| At the cap \|
	810	\| --- \| --- \| --- \| --- \|
	811	\| A comped account's monthly budget \| `COMPED_MONTHLY_CEILING_MICROS`, or the account's own Limit in its terms \| $150 a month \| New work on the account (agents, checks, workflows, builds) is refused with "<name>'s monthly budget for g1t's own agents is used up … Staff can raise it in sudo". Runs already going finish; the per-run cap still applies to them. It lifts when staff raise the budget or the month turns (UTC). \|
	812	\| The daily breaker \| `PLATFORM_DAILY_SPEND_CAP_MICROS` \| $75 a day (UTC) \| New agent runs on g1t's hosted models that g1t would pay for are refused until 00:00 UTC. Not paused: agents on the workspace's own model provider, checks and builds, and workspaces paying with live payments on the plan (not given by staff) or an enterprise contract. In test mode that exemption covers no one. \|
	813
Costs: Cloudflare's subscriptions read from Cloudflare each day, the estimate only until then; sudo's costs split into Costs & margin and Bill & pricing1d ago	814	`0` turns either off. Cloudflare's subscriptions are read from Cloudflare
	815	each day (`cf_subscriptions`) and shown on the page only;
	816	`CLOUDFLARE_FIXED_MONTHLY_MICROS` ($30) stands in until a read works.
Spend caps: a monthly budget for comped workspaces and a daily breaker on what g1t pays2d ago	817
	818	The checks are cheap: `reserve` reads today's total (one indexed sum) and,
	819	for a comped account, its month's comped rows. Refusals come back as
	820	`paused`, which the compute gate honours for every plan, internal and
	821	enterprise included (`packages/contracts/src/compute.ts`). The runner tells
	822	billing whether an agent run is on hosted models (`hostedModel` on
	823	`reserve`); a caller that does not say is treated as hosted.
	824
	825	### Alerts
	826
	827	All to `COSTS_ALERT_EMAIL` (`hey@flagon.io`), through the `EMAIL` binding:
	828
	829	- Comped budget: at 50, 75, 90 and 100%, once each per account and month
	830	(`budget_alerts`), checked every 15 minutes. A jump past several levels
	831	sends only the highest.
	832	- Breaker: at once, from the charge that trips it; if that email fails,
	833	the 15-minute cron sends it (`spend_breaker.told_at`).
	834
	835	While the breaker is open or a comped budget is used up, every sudo page
	836	shows a red Spend cap bar.
	837
	838	### Raising and lifting
	839
	840	- Raise a comped budget: sudo → the workspace → Billing → Terms, set
	841	Limit $ to the new monthly budget (blank goes back to the default),
	842	with a note. It applies to the next start; nothing to deploy. The change
	843	is in the account's audit log.
	844	- Lift the breaker for today: sudo → Costs & margin → **g1t's own
	845	spend → Lift for today**, with why (`admin_lift_breaker`; audit action
	846	`breaker_lifted`). It resets by itself at 00:00 UTC.
	847	- Change a default: edit the variable in `services/billing/wrangler.jsonc`
	848	and deploy g1t-billing.
Billing keeps Stripe's view itself: the saved card on the account, missed events replayed every 15 minutes, and the endpoint kept1d ago	849
sudo: reset a test workspace's billing so it starts again as a new customer; refused on a live Stripe key, for comped workspaces and for an enterprise's1d ago	850	## Resetting a test workspace
	851
	852	sudo → the workspace → Reset billing (testing) (`admin_reset_billing`)
	853	returns a workspace used for testing to how a new customer starts. It
	854	deletes the workspace's rows from every billing table: ledger and balance,
	855	plan and plan payments, limits and limit requests, trial grant, invoices,
	856	holds, card checks, alerts sent, price notices, month-end snapshots and
sudo: the billing reset no longer names sandbox_months (dropped in 0015), checked against the migrations by a test; a failed reset says why instead of an error page1d ago	857	closes, storage meters, token usage, spikes, sales records and
sudo: reset a test workspace's billing so it starts again as a new customer; refused on a live Stripe key, for comped workspaces and for an enterprise's1d ago	858	notes, `workspace_costs`, its workspace margin alert and its own billing
	859	account. It keeps `own_counts` (what Cloudflare's bill is compared with)
Merge branch 'main' into worktree-agent-a69aeabc4b0deeb9713h ago	860	and the audit log, which records the reset with the note, the number of
	861	rows and what g1t had paid for. The workspace, its members and its
	862	repositories are identity's and repos' and stay.
	863
	864	What g1t paid for is kept. The wiped usage still happened: AI Gateway
	865	still prices its model calls and Cloudflare still bills its sandboxes. So,
	866	in the same batch as the deletes, the reset writes `reset_costs`: a row per
	867	day and bucket the workspace had cost on (the ledger's cost, month-end
	868	meters' cost, and the value the reconciliation gave it), plus one row for
	869	the reset itself (bucket `''`, nothing in it) so every reset is on record.
	870	`reset_at` is the same instant as the reset's `admin_actions` entry. The
	871	costs run reads the rows back as the workspace's usage on their days, all
	872	of it given away as testing resets: `models` drift compares AI
	873	Gateway with the ledger's model cost plus what resets kept, the statement
	874	lists it under Given away, and the workspace stays in Who g1t paid
	875	with its cost given. The rows are never wiped by a later reset, and a
	876	rename moves them. Re-running the analysis reads the same rows and gives
	877	the same answer.
	878
	879	Resets before migration 0046 kept nothing; their wiped rows are gone and
	880	nothing is made up for them. The costs run finds them in the audit log
	881	(`admin_actions`, action `reset`) with no `reset_costs` at the same
	882	instant, and the `models` drift detail says AI Gateway's figure includes
	883	usage wiped by a testing reset of that workspace on that day, rather than
	884	calling it a leak. syntaqx was reset on 2026-10-07 after about $8.60 of
	885	model usage from 2026-10-02 to 2026-10-07; that usage is in the 7-day
	886	window until the run of 2026-10-13 and leaves it on 2026-10-14.
sudo: reset a test workspace's billing so it starts again as a new customer; refused on a live Stripe key, for comped workspaces and for an enterprise's1d ago	887
	888	Billing refuses it while `STRIPE_SECRET_KEY` is a live key, for comped
sudo: a billing reset runs the costs analysis again so every figure is fresh; every submit button shows it is working (CSS only); no margin percentage on less than a cent sold1d ago	889	workspaces, and for a workspace an enterprise pays for. It then runs the
	890	costs analysis again (as Run the analysis now does), so the margin
	891	figures drop the workspace's past usage at once; if that run does not
	892	finish, the page says so and the button does it.
sudo: reset a test workspace's billing so it starts again as a new customer; refused on a live Stripe key, for comped workspaces and for an enterprise's1d ago	893
Billing keeps Stripe's view itself: the saved card on the account, missed events replayed every 15 minutes, and the endpoint kept1d ago	894	## Stripe
	895
	896	Billing keeps what it needs from Stripe so reads never wait on it, and
	897	hears of changes three ways (`webhooks.rs`, `stripe_sync.rs`).
	898
Usage, Billing settings and prepaid AI credit; fixes from the UX audit16h ago	899	API version. Every request sends `Stripe-Version: 2025-02-24.acacia`
	900	(`stripe::STRIPE_VERSION`), the version billing's field reads are written
	901	for; without it Stripe answers at the account's default. Webhook events
	902	come at the destination's own version: billing reads an invoice's
	903	subscription from `subscription` or `parent.subscription_details.subscription`.
	904	Raising the version is a code change: read Stripe's upgrade notes for every
	905	field billing reads.
	906
	907	Failures. No Stripe failure reaches a page as a 500: each payment page
	908	(`page_opened`), the portal, confirmations and plan changes turn it into
	909	`stripe::friendly` (Stripe's own message, never the request or a key), and
	910	log the full error with the workspace. Every payment page is recorded
	911	through one insert (`CHECKOUT_INSERT`), checked against the migrations by
	912	`every_checkout_insert_fills_the_table`, and has an idempotency key
	913	(`page/<purpose>/<workspace>/…/<10-minute bucket>`).
	914
Stripe's webhook secret is a Worker secret, STRIPE_WEBHOOK_SECRET, from a destination made in Stripe's dashboard1d ago	915	The webhook. A destination made in Stripe's dashboard (Developers →
	916	Webhooks → Add destination) with the endpoint URL
	917	`https://api.g1t.sh/stripe/webhook`, in the mode of billing's key (at
	918	launch, make one in live mode and put its secret). Its signing secret
	919	(`whsec_…`: the destination, Signing secret, Reveal) is the billing
	920	Worker's secret:
	921
	922	```sh
	923	cd services/billing && npx wrangler secret put STRIPE_WEBHOOK_SECRET
	924	```
	925
	926	Without it every event is refused with 400. After rolling the secret in
	927	Stripe, put the new one; during the roll Stripe signs with both, so there
	928	is no gap. The event list need not be exact: billing adds any event it
	929	handles that the destination does not send (daily, or Fix destination
	930	in sudo → Stripe), and enables it again if Stripe disabled it. It never
	931	changes the secret. sudo → Stripe shows whether the secret is set, the
	932	destination and its status, missing events, and the latest events.
	933	Events are claimed once each in `stripe_events`; a handler that fails
	934	forgets its claim, and Stripe retries.
Billing keeps Stripe's view itself: the saved card on the account, missed events replayed every 15 minutes, and the endpoint kept1d ago	935
	936	What is kept, and how it stays current
	937
	938	\| Kept \| Where \| Refreshed by \|
	939	\| --- \| --- \| --- \|
	940	\| Saved card (brand, last 4, expiry) \| `accounts.card_`, `card_synced_at` \| `customer.updated`, `payment_method.`, `setup_intent.succeeded`; forgotten when g1t sets a default card, so the next read asks once; the daily pass for cards older than 7 days \|
	941	\| Plans \| `subscriptions` \| `customer.subscription.`, `invoice.`; a read asks Stripe at most hourly once a period is over; the daily pass for rows older than a day \|
	942	\| Payments, refunds, disputes \| ledger, `checkouts`, invoices \| their events \|
	943
	944	Every cron run (every 15 minutes) replays missed events: Stripe's event
	945	list from an hour before `stripe_sync.through`, oldest first, through the
	946	same once-only claim. `through` moves to 5 minutes before now when all were
	947	handled, back to the first failure otherwise, and stays when more than
	948	1,000 events were listed. Claims stuck at `handling` for 10 minutes are
	949	dropped so the replay retries them. The first run reads 3 days back.
	950
Stripe's webhook secret is a Worker secret, STRIPE_WEBHOOK_SECRET, from a destination made in Stripe's dashboard1d ago	951	Daily (`keeper::DAILY`): the destination at billing's address is
	952	enabled again if Stripe disabled it and given any missing event, audited as
	953	`stripe`/`webhook`; then up to 25 stale cards and 25 stale plans are read
	954	again.
Billing keeps Stripe's view itself: the saved card on the account, missed events replayed every 15 minutes, and the endpoint kept1d ago	955
	956	What still calls Stripe on a request: starting a payment page, a plan
	957	or a card check; opening the billing portal; settling a page the person
	958	came back from; renaming a workspace (the customer's name). Nothing a page
	959	view reads.
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar16h ago	960
Merge Stripe Tax, the card fee on card payments, and one free workspace per person15h ago	961	## Tax and the card fee
	962
	963	Owner decision 2026-10-08. Code: `services/billing/src/tax.rs` (what is
	964	kept, the address hold), `stripe.rs` (every request's tax fields),
	965	`invoices.rs`, `webhooks.rs`, `ai.rs`; migration
	966	`0043_tax_and_card_fees.sql`.
	967
	968	### What Stripe is asked
	969
	970	Every price excludes tax (`tax_behavior=exclusive`) and carries tax code
	971	`txcd_10103001` (software as a service, business use; the card fee too,
	972	since a fee for paying for a sale follows the sale). Fields are valid for
	973	`2025-02-24.acacia`.
	974
	975	\| Request \| Tax \| Card fee \|
	976	\| --- \| --- \| --- \|
	977	\| Checkout, plan or Security (`subscription_fields`) \| `automatic_tax[enabled]`, `billing_address_collection=required`, `tax_id_collection[enabled]`, with a customer `customer_update[address]=auto` and `[name]=auto`; the subscription keeps automatic tax for every renewal \| A second recurring line, Card processing fee \|
	978	\| Subscription on a saved card (`saved_subscription_fields`) \| `automatic_tax[enabled]`; a customer Stripe Tax cannot place fails, and the person is sent to Checkout, which asks for the address \| `items[1]`, the `card_fee` product \|
	979	\| Checkout, prepay (`prepay_fields`) \| As above \| By card only; none by bank transfer \|
	980	\| Checkout, AI credit (`credit_fields`) \| As above \| Its own line \|
	981	\| Checkout, card check (`card_check_fields`) \| Setup mode: nothing charged, nothing taxed. `billing_address_collection=required`, and the card's address is copied onto a customer with none (`fill_address`) \| — \|
	982	\| Auto-reload (`charge_saved`) \| `POST /tax/calculations` first (credit and fee as lines), the PaymentIntent for the total, then `POST /tax/transactions/create_from_calculation` with the PaymentIntent as reference; a refund reverses its share (`create_reversal`, `mode=partial`) \| In the calculation and the amount \|
	983	\| Workspace invoice, month close and threshold (`invoice_workspace`) \| `automatic_tax[enabled]` on the draft; each item `tax_behavior`, `tax_code` \| An item Card processing fee, when the default payment method is a card \|
	984	\| Enterprise invoice (`invoice_enterprise`) \| The same \| Never \|
	985	\| Products (`Stripe::product`) \| Made with `tax_code`; one found without it is given it \| The `card_fee` product, `metadata[g1t]=card_fee` \|
	986
	987	### What is kept
	988
	989	A payment credits the balance with what it paid for, never its tax or fee:
	990	prepay credits the page's `amount_subtotal` less the fee line
	991	(`credit_prepayment`), a workspace invoice `amount_paid − tax − fee`
	992	(`credit_invoice`), AI credit its credit amount, and `plan_payments` the
	993	plan's invoice less its tax and Card processing fee lines
	994	(`stripe::invoice_split`). Each payment's tax and fee are rows in
	995	`tax_and_fees` (`<reference>/tax`, `<reference>/card_fee`; the enterprise's
	996	account id in `workspace` for its invoices), with the PaymentIntent, so a
	997	refund (`charge.refunded`) gives back the balance, tax and fee in
	998	proportion (`tax::refund_split`, negative rows under `refund/<charge>/…`).
	999	`workspace_invoices.fee_micros` and `tax_micros` sit beside each usage
	1000	invoice.
	1001
	1002	- Statement. Tax and Card processing fees are their own lines per
	1003	day (`StatementLine.passed_micros`), never in `charged_micros`; totals
	1004	`tax_micros`, `card_fee_micros`. The CSV has a row a day for each.
	1005	- Margin. Cash never holds them, so margin is untouched. sudo → Costs
	1006	shows Tax collected and Card fees passed on for the range
	1007	(`OverallMargin.tax_collected_micros`, `card_fees_micros`). Tax is owed to
	1008	the authorities: file it from Stripe Tax's reports, never from g1t's.
	1009
	1010	### No address
	1011
	1012	Stripe Tax needs a country (in the US a ZIP code, in Canada a postal code
	1013	or province: `stripe::address_places_customer`). Before a workspace
	1014	invoice is drafted, g1t checks the customer; without an address, or when
	1015	Stripe leaves the draft at `requires_location_inputs` or refuses with
	1016	`customer_tax_location_invalid`, nothing is charged:
	1017	`accounts.tax_address_needed_at` is set, the owners are emailed once
	1018	(`notify_owners`), and Billing shows Add a billing address. Saving
	1019	Invoice details with an address Stripe Tax can use clears it, as does a
	1020	charge that goes through. Work is not stopped for it; the limits still
	1021	apply. Auto-reload without an address fails like a declined card (turned
	1022	off, owners told). An enterprise's invoice is not sent without an address:
	1023	sudo → the enterprise → Invoices → Billing address (`admin_enterprise_address`,
	1024	with its tax ID; audited `billing_address`).
	1025
	1026	### The card fee
	1027
	1028	`card_fee_cents` grosses Stripe's fee up so the amount paid for is left
	1029	after it: `(amount + 30¢) / (1 − 2.9%)`, rounded up; $0.91 on $20, $1.06
	1030	on $25. It is worked out on the amount before tax, so Stripe's fee on the
	1031	tax itself (a few cents) is g1t's. It is shown before paying: the plan card
	1032	and pricing page (`Plan.card_fee_cents`), AI credit (*Card processing fee
	1033	$1.06, plus tax where it applies*), Prepay. Never on a bank transfer or an
	1034	enterprise's (`send_invoice`) invoice. Meters stay at cost + 20% and models
	1035	at the provider's price plus the agent rate (price versions in migration
	1036	0040); the fee is passed through, not margin.
	1037
	1038	### Tax-exempt customers and tax IDs
	1039
	1040	g1t never sets `tax_exempt`. For a customer who sends an exemption
	1041	certificate, set it in Stripe's dashboard (Customers → the customer → Tax
	1042	status: Exempt, or Reverse charge); Billing then says so. Tax IDs come
	1043	from Checkout (`tax_id_collection`) or Invoice details (`set_billing_details`,
	1044	validated against Stripe's types in `details::TAX_ID_TYPES`); Stripe checks
	1045	EU VAT numbers and Stripe Tax applies a reverse charge where it should.
	1046	Billing shows Stripe's `verification.status`.
	1047
	1048	### In Stripe's dashboard (not done by g1t)
	1049
	1050	1. Settings → Tax → Get started: turn on Stripe Tax in live and test
	1051	mode.
	1052	2. Origin address: Flagon, Inc.'s head office address.
	1053	3. Default tax code: Software as a service, business use
	1054	(`txcd_10103001`); default tax behavior: exclusive.
	1055	4. Registrations: add each jurisdiction where Flagon is registered to
	1056	collect (its home state at least; then states as thresholds are
	1057	crossed, which Stripe Tax's monitoring flags; the EU's OSS and the UK
	1058	if selling there). Stripe collects only where a registration exists.
	1059	5. Customer portal: tax ID and address updates are already allowed
	1060	(`portal_configuration`).
	1061	6. Refund an invoice through a credit note, so its tax is reversed in
	1062	Stripe Tax.
	1063
	1064	## Free workspaces
	1065
	1066	Owner decision 2026-10-08: one free workspace per person, and a free
	1067	workspace adds no one. Billing answers one question, `free_workspaces`
	1068	(`credits.rs`): which of the given workspaces are on no paid plan
	1069	(`plan_kind_for` is `Free`). The plan, an enterprise's terms and a 100%
	1070	discount (flagon-io) count as paid; with payments off nothing is free.
	1071	Identity asks it (`services/identity/src/paid.rs`) and refuses with
	1072	`payment_required`:
	1073
	1074	\| Where \| Refused when \|
	1075	\| --- \| --- \|
	1076	\| `create_workspace` \| The person owns any free workspace. Several from before are kept (grandfathered); none can be added until each is paid for or deleted. \|
	1077	\| `add_member`, `invite_member` \| The workspace is free. \|
	1078	\| `add_collaborator` \| Someone outside a free workspace (a username who is not a member, or an address). Members' roles are fine. \|
	1079	\| `accept_invite`, `respond_repo_invitation` \| The invite's workspace (or repository's) is free now: it waits. A sign-up with such an invite makes the account without joining. \|
	1080
	1081	`@g1t` is never counted as someone added. If billing cannot be asked, the
	1082	change is refused for now ("try again"), never let through. The site says
	1083	so first (New workspace, People, a repository's Access, from the same RPC);
	1084	the API and MCP pass identity's refusal on as `402`.
	1085
Teams and CODEOWNERS, labels and milestones, dependency updates, the security suite, and a clearer top bar16h ago	1086	## The Security and quality activation
	1087
	1088	A second monthly subscription a workspace can hold beside the plan
	1089	(`Feature::Security`, `feature = 'security'` in `subscriptions`). It turns
	1090	on the security suite's paid features for the workspace's private
	1091	repositories: custom secret patterns, validity checks, delegated bypass,
	1092	code scanning, dependency review and the security overview. Public
	1093	repositories have them free; secret scanning, push protection,
	1094	vulnerability alerts and security updates are free everywhere.
	1095
	1096	- Price. The price book's `security_activation` meter (unit
	1097	`workspace-month`, `source` `list`, markup 0): 10,000,000 micros, $10,
	1098	from migration `0037_security_activation.sql` with its first
	1099	`price_versions` row and a public `price_changes` record. `plan()` and the
	1100	`prices` RPC read it (`features::security_plan_at`); if the price book
	1101	cannot be read, $10. Nothing in the web app hard-codes it. A change is a
	1102	new price version, like any other: noticed on the pricing page and
	1103	applied from its `effective_at` to new subscriptions. Subscriptions
	1104	already running keep the amount Stripe has until they are changed in
	1105	Stripe.
	1106	- Stripe. Its own subscription and its own product, tagged
	1107	`metadata[g1t]=security` (the plan's is `plan`). Started from the Billing
	1108	page with `subscribe` (`feature: security`) on the checked card, or
	1109	through Checkout; ended with `cancel_subscription` (`feature: security`)
	1110	at the period's end. Its invoices count in `plan_payments` like the
	1111	plan's, as paid revenue.
	1112	- Who has it. `has_feature(workspace, security)`: on with an active
	1113	subscription, with comped terms or as an enterprise's workspace, or when
	1114	Stripe is not configured. The plan's allowance (`allowances.plan`) does
	1115	not include it. Refusals are `PaymentRequired` with the price from the
	1116	price book and the Billing page's address.
	1117	- Where it is checked. The security service, on each paid call for a
	1118	private repository (`suite::entitled`) and before using custom patterns
	1119	in a push (`patterns_for`). When billing cannot be reached it is taken
	1120	as off: a paid feature waits rather than running unpaid.
	1121	- Fixes. "Fix with g1t" runs g1t's agent, charged as agent usage, never
	1122	to the activation.
	1123	- Sales figures. MRR in sudo counts `feature = 'plan'` only; the
	1124	activation's subscriptions are not in it yet.

This file's history is long; its oldest lines are credited to the oldest commit read.