). guide and reference take an optional topic and return only the matching sections; guide with no topic ends with every page's markdown link. explain_error names the code's page, https://docs.gemmein.com/errors/
. Offline: the section index ships with the server.

Removed:
- Pricing
  Was: Holding the bill and the ceilings at a price step from the dashboard.
  Now: There is no band to hold: the price is the tier the founder picks on Usage & billing, and the tier's people are where the ceilings stop.
- Signing in the CLI
  Was: A CLI key shown on the Setup page and rotated on Secret keys.
  Now: There is no CLI key. The CLI holds its own key in gemmein/.data/cloud.json after the browser approval; Revoke on the Approvals page ends it.
  Codes no longer answered: cli_key_unavailable
- Going live
  Was: A suspended account answered every request, on every app, with account_suspended.
  Now: No request is answered account_suspended. A paused Live answers 503 live_paused; Development keeps working.
  Codes no longer answered: account_suspended
- Payments
  Was: Pasting a customer portal link on the Payments page.
  Now: Gemmein makes the portal; `g.subscriptions.manage()` opens it for the member. There is nothing to paste.
  Codes no longer answered: portal_not_set_up, invalid_portal_link, payments_not_set_up

Added:
- Live actions: The dashboard's Approvals page lists the machines working now (Revoke ends one at once), the requests waiting (Cancel) and the history of what each approval was used for.
- Collections: The collection file holds every setting (rule, means, unlockedBy, publishing, openFields, directInitiation, fields). A key it doesn't know is refused by name, and sync applies the file's settings to Development.
  New error codes: unknown_collection_setting, invalid_fields, invalid_direct_initiation
- Secrets: A provider's own signing secret (Stripe's whsec_…, or one an HMAC sender gives you) has a home: pipe it to `npx gemmein relays secret ` (Development) or paste it on the relay's page in the dashboard.
  New error codes: provider_secret_required
- Server keys: `npx gemmein keys create --name  --env development|live --access :,…` makes a server key with exactly that access on one browser approval; the key goes to the secrets file, never the screen. `keys` lists them, `keys revoke` ends one.
  New error codes: key_name_taken, key_not_found, invalid_key_plan, no_environment
- Server keys: `gemmeinServer(sk, { expects })` compares the key's access with what the app needs before the first call; too narrow or too broad throws key_scope_mismatch with err.missing or err.extra. whoami returns the key's access.
  New error codes: key_scope_mismatch
- Domains: `npx gemmein domains add ` and `domains remove ` run on one browser approval; add prints the DNS records as one list and the one thing to do.
  New error codes: domain_exists
- Allowed addresses: Once an app is live, a page on one of its verified domains that still calls with the Development key is answered, and Live's Problems says so once a day per domain (`dev_key_on_live_site`); `npx gemmein domains` and `npx gemmein check` print it. Switch the live build to the Live key (`npx gemmein keys app`).
- Payments: `welcomeBonus` on a plan or product adds credits once per member, only on their first paid payment in the app. No relay needed.
- Payments: grant_credits takes `ref`: once per person and ref, forever.
- Payments: A plan-start email (gemmein/emails/plan-start.html) goes out when a paid plan or its free trial begins; each paid subscription invoice writes a receipt (in the app's receipts collection, when it keeps one); a Payment Link return carries a display-only ?paid= marker for the thank-you screen.
- Members: A sign-in from a new device or country emails the member "New sign-in to " (naming the country, never the address) with a single-use sign-out-everywhere link. Not on their first sign-in ever, read from the person's own record, so a person back after months away is still told; the owner can switch it off.
- Members: currentUser() says why a stored session stopped working: ended "expired" or "revoked".
- Members: g.auth.onSignedOut(listener) is the one place to route to sign-in: it fires when the session ends however it ended (reason "signed_out", "revoked" or "expired"), after the SDK has cleared its token, and returns a function that stops listening.
- IP addresses: The founder sees each signed-in device's IP address and country on the person's page, and each security event's IP address in Logs, with a Copy button. The person's own devices() and the new-sign-in email name the country only. A CLI approval page shows the full IP address the request came from.
- IP addresses: An IP address is removed after 30 days (the event stays in Logs without it). The person's export carries the addresses still inside 30 days (sessions and signIns); deleting the person removes the addresses on their events, and the events stay.
- IP addresses: When a session ends, its device record (label, country and IP addresses) is deleted at once and leaves the list; the sign-in event in Logs keeps the device label and country.
- Server SDK: The server client's update takes { published, ifVersion }, and its get, list, create and update are typed: collection("feed").
- Collection features: An open field can be "one per person of a, b, c" (polls, RSVPs): each person holds one choice, set with open(id).choose(field, choice); the record carries a count per choice.
- Collection features: The app is a party on a direct collection: your server writes { from: "app", for: personId } and a member replies { for: "app" }; your human answers from the dashboard.
- Email and domains: Designing the app's emails is a default build step; `npx gemmein check` and the go-live list warn when emails still use Gemmein's plain design. The purchase email for a credit pack says it's credits.
- Relays: On every receiver scheme the relay chooses whose secret it is: Gemmein makes it, or you paste the sender's. A pasted secret is plain ASCII, not a repeated pattern, and at least 24 characters (22 when it mixes upper- and lower-case letters and digits); a Standard Webhooks secret is whsec_…. A stripe receiver always uses Stripe's own.
- Relays: A relay's trigger kind can change freely under gemmein dev; once synced, the cloud refuses the change and names the two ways out (rename it, or `npx gemmein sync --prune` in Development).
  New error codes: trigger_kind_fixed
- Relays: signedPayload rules, checked at save: the placeholders are {timestamp}, {url}, and ONE of {body}, {params} or {token}, which ends the text. Each appears once. Letters, digits and . : _ - go around them, at most 40 characters. A digit or {params} never comes right after {timestamp}. {timestamp} must appear when a timestamp is named and needs a source; {token} needs tokenField. A signature inside the body never signs {body} or {params}. timestampHeader, timestampKey and timestampField: one at most. signatureKey and timestampKey never share a name. The separator is , or ;. A break is refused with 400 invalid_definition, saying which and how to fix it. A recipe that saves but differs from how the sender signs answers 401 bad_signature on every event.
- Relays: A receiver whose recipe is ed25519 or ecdsa-p256-sha256 checks the sender's PUBLIC key. Paste it on the relay's page or pipe it to `npx gemmein relays secret `, as the sender shows it: hex, base64 or a PEM block. Gemmein never makes one: asking answers 400 provider_secret_required. A private key, a key of another kind, or anything that is not a key is refused with 400 invalid_input. A public key is never a secret: on an HMAC recipe a PEM or DER key is refused, and changing a recipe between a public key and a secret always clears the stored value in the same write, on save and on Promote; a paste racing such a change answers 409 version_conflict and stores nothing; an HMAC recipe that holds a key anyway refuses every event and raises the Problem relay_key_as_secret. A public-key change is on Logs by its fingerprint, never the key.
  New error codes: provider_secret_required, invalid_input, relay_key_as_secret
- Relays: One rule for relays whose sender doesn't sign the event itself: a signature recipe that signs only a token ({token} ends signedPayload, as Mailgun signs) and the shared_token scheme. By default such a relay only writes records and calls your URL. Granting (grant_access, grant_credits, grant_plan, fulfil_product, start_run), taking away (revoke_access, revoke_plan, refund_product), emailing the person (email_person) and creating people (a map naming person_email) answer 400 invalid_definition, on the dashboard, the CLI, sync, gemmein dev and Promote (its dry run names it as not carried). person_id and person_token never create anyone. To let a relay act anyway, set trigger.trustUnsignedEvents: true on it: the save answers a one-line warning (the CLI and sync print it once), the relay's page shows it beside the setting, Logs records the change before and after, and Promote carries it with the warning in its dry run. The opt-in is refused on a sender that signs the event. A record a relay writes never fires a data_change relay. A stored relay that breaks the rule refuses every event with 401 bad_signature and raises the Problem relay_unsigned_event. An event that arrived unsigned never acts later: if the relay changed to act without the opt-in before it ran, it ends without running, and a replay of it answers 409 unsigned_event. With the opt-in on, a save that widens what a captured call buys answers the warning again. The Go live and Promote previews list each opted-in relay with its warning and each relay they won't copy. The RevenueCat and shared-token templates carry the setting, with the warning in their note.
  New error codes: invalid_definition, relay_unsigned_event, unsigned_event
- Relays: {url} in a recipe is the receiver URL exactly as the relay's page shows it, never the Host header. A call that adds anything after it, a query string included, answers 401 bad_signature. A receiver reads a form post (application/x-www-form-urlencoded) as its fields, so a map names them directly.
- Relays: A recipe whose signed text is not the raw body ({params} or {token}) accepts each signature once, still for 24 hours after the relay is deleted. A {token} recipe (Mailgun) does not authenticate the event: a captured signed call verifies once with any body within 5 minutes, so check such an event with the sender's API before granting. Senders that sign no timestamp (GitHub, Intercom, Square, Twilio) are deduped by event id, or by body within the UTC day.
- Relays: A signature header listing more than 8 signatures is refused with 400 too_many_signatures. A relay saved before the rename to signature answers 401 scheme_renamed until its definition is saved with "scheme": "signature".
  New error codes: too_many_signatures, scheme_renamed
- AI tools: Under gemmein dev, your own pipeline can hand back files at a loopback http URL (the cloud still takes https only); the SDK's pipeline helper fails the run, and the hold returns, when the hand-back is refused.
- AI tools: Every AI answer passes at most 32 MB; past it the answer is cut where it stands and costs its ceiling.
- Test kit (Development): `npx gemmein members add ` makes test members at @.gemmein.test; `npx gemmein mail` reads their sign-in codes and every email the app sends them, with headers and SPF/DKIM/DMARC. Development only; their mail never leaves Gemmein.
  New error codes: test_kit_development_only, test_members_full, test_kit_capped, not_a_test_member
- Test kit (Development): The founder's actions on test members from the CLI: approve, send-back, suspend, unsuspend, sign-out --everywhere.
  New error codes: changed_since_read
- Test kit (Development): `npx gemmein pay --as  ""` pays through the app's real checkout with Stripe's test card and waits for the webhook; `npx gemmein refund ` refunds it. They run only on a test-mode Stripe key and are refused on a live one. Two optional rows on a sandbox key serve them: Charges and Refunds (Write) and Checkout Sessions (Read).
  New error codes: test_pay_live_key_refused, test_pay_local, test_pay_unavailable, test_refund_refused, test_refund_outcome_unknown, test_checkout_unknown, payment_not_found, unknown_item, stripe_not_connected
- Hosted connector: AI apps with no terminal — ChatGPT, Claude, Lovable, Replit, Bolt, v0 — add https://api.gemmein.com/mcp and build and run a Gemmein app from the chat. The ten tools of `npx -y @gemmein/mcp` need no account. One approval on the same page `npx gemmein login` uses lets the connector build in Development: pull and sync the gemmein/ files (the files win, the diff shown first), or declare collections, plans, relays, AI tools and emails one at a time; test members, test mail and sandbox test payments. Live is never part of it: each Live change is approved on its own, with the code Gemmein emails — except going live, where paying for the plan is the confirmation. Reading Live is its own approval line, and every read is on Logs. Secret keys are shown once in the browser, never in the chat. The connection lasts 30 days and is revoked on Approvals. `npx gemmein dev` serves the same /mcp on this computer.
  New error codes: sign_in_required, invalid_token, insufficient_scope, key_in_browser, token_in_url, host_refused, origin_refused
- Hosted connector: Six read-only Live tools on the live:read grant answer "how is my app doing?" without the dashboard: live_overview (people and revenue this month against last, errors in the last 24 hours, what waits on the founder, paused or not), live_errors (each code with counts, first and last seen, an example Logs row and its docs page), live_usage (meters against the plan, AI calls, credits used and given, emails sent), live_webhooks (relay runs, retries, each failure's reason), live_emails (sent, bounced, complained, deferred per template) and live_inbox (conversations, unanswered first; one in full). Each read is on Logs and changes nothing.
  New error codes: unknown_relay, thread_not_found
- Hosted connector: inbox_reply answers a customer inside an existing Inbox conversation, from the app's support address, exactly as the founder's reply — its own approval line (live:inbox_reply, "Reply to your customers' messages"), the one standing Live action. Never after an automatic message (inbox_auto_reply), at most 3 AI replies in a row (inbox_reply_cap), never while the last message can't be read (inbox_unreadable), at most 60 an hour per connection and 300 per app (inbox_reply_limited). Only to senders whose email passes DMARC, as the receiving provider saw it (inbox_unauthenticated otherwise; you can reply to anyone yourself); at most 10 a day per conversation (inbox_thread_limited) and 5 an hour per address (inbox_recipient_limited); Live's side of the Inbox only. Each reply shows in the Inbox as sent by your AI.
  New error codes: inbox_auto_reply, inbox_reply_cap, inbox_unreadable, inbox_reply_limited, inbox_unauthenticated, inbox_thread_limited, inbox_recipient_limited
- Server keys: A server key can hold the support Inbox: `--access inbox:read,inbox:reply` (the dashboard's "Read your customers' support messages" and "Reply to your customers' support messages"). gemmeinServer(sk).listInboxThreads(), getInboxThread(id) and replyInboxThread(id, text) — GET /server/inbox/threads, GET /server/inbox/threads/:id, POST /server/inbox/threads/:id/reply — run the same guard and caps as the connector; a key's reply shows as sent by the key.
  New error codes: inbox_auto_reply, inbox_reply_cap, inbox_unreadable, inbox_reply_limited, thread_not_found, inbox_unauthenticated, inbox_thread_limited, inbox_recipient_limited
- Errors: A refusal in Development, from a secret key, the CLI or the MCP connector carries `docs`, the code's own page: `{ code, message, docs: "https://docs.gemmein.com/errors/" }`. `GemmeinError` has `.docs` (JS and Swift). A request made with the Live app key is answered without it, so nothing a customer can read names Gemmein.
- What changed: This feed: `npx gemmein changes [--since ] [--json]`, the MCP tool `changes`, and https://docs.gemmein.com/changes.txt (and .json). The guide opens with its version and what changed.
- Founder sign-in: A founder can turn on an authenticator app (TOTP: 6 digits, 30 seconds) in the dashboard's Settings › General, each person on an account for themselves. With it on, signing in to the dashboard asks for its code after the emailed code, and so does deleting a Live collection, a domain of a live app or the account, approving such a delete for an AI, and turning it off. Ten single-use recovery codes are shown once and work in its place. Nothing in Development asks; prices, plans, keys, Stripe, going live and promote never do. Ten wrong codes in a row slow the next try (1 minute up to a day) and email the founder — never a lockout. For an AI: a Live delete you ask for waits on your human's Approve as before — that page may now ask them for the code.
  New error codes: app_code_required, app_code_invalid, app_code_sign_in_expired, app_code_already_on, app_code_not_pending, app_code_not_on, app_code_wait

------------------------------------------------------------------------

This record starts after Gemmein 0.22.1.

------------------------------------------------------------------------

No longer true (if you remember one of these, it is wrong now):
- Was: Gemmein runs nothing for you: it has no compute of its own, and a relay only passes events along.
  Now: Gemmein runs its own AI tools and relays. A relay receives the event, maps fields and carries out Gemmein's own actions; it never runs code you write or reshapes data with custom logic. An external pipeline tool and your own server code run on your own host.
- Was: There are no native mobile SDKs.
  Now: Native mobile SDKs exist: @gemmein/sdk/expo (Expo and React Native) and GemmeinSwift (Apple platforms).
- Was: Gemmein charges for each active person.
  Now: Each Live app pays a flat price for the tier its founder picks; active people are a limit, never a price, and there is never a per-person invoice line.
- Was: Every payment lands in a single Stripe account, and payments are Stripe-only.
  Now: Money always lands whole in the founder's own payment provider account: Stripe is built in, others come through a relay. Gemmein never holds it.
- Was: The free (default) plan can't carry a credit allowance.
  Now: The free (default) plan may carry credits.perPeriod (granted once per person per calendar month, UTC, at their first spend) and/or credits.once, a welcome allowance for a person who never held a paid plan.
- Was: People can't upload their own audio for transcription.
  Now: A transcribe tool's file input takes audio the person uploads with g.ai.upload(tool, file) (mp3, m4a, wav, webm, ogg, flac; 25 MB, 14 MB on Google), a file they already own, or an https URL.
- Was: Signing in to your own app as its owner lifts your role, so the app can show you everyone's records.
  Now: In the app the owner is an ordinary customer and reads only what the rule gives them. The Gemmein dashboard is the admin view; an in-app admin screen goes through your own server with a read-only secret key.
- Was: sends_disabled means the owner switched in-app sending off.
  Now: sends_disabled means direct messages are off for this collection; addressed records are sent from the dashboard or a relay.
- Was: A secret key can only read and update records; it can't create or delete them.
  Now: A secret key gets one of three levels per collection (reads only; reads and writes; or reads, writes and deletes), or is a full key for every collection. A key that writes creates and updates records under any rule; name whose record it is with { for } or { from }.
- Was: You can paste your own Stripe Payment Link and signing secret instead of connecting a key.
  Now: Selling through Stripe needs the restricted-key connection on the Payments page; Gemmein makes each Payment Link.
- Was: Live storage is 10 GB per app.
  Now: Live storage is flat per tier (5 GB, 50 GB or 150 GB) plus 50 GB per storage pack; Development is capped at 1 GB.
- Was: The CLI links to the cloud with a CLI key your human copies from the Setup page.
  Now: `npx gemmein login` prints a link and a code; your human presses Approve in the browser. No key is ever shown, copied or pasted.
- Was: Live actions wait for you to type a confirmation.
  Now: Each Live action is approved in the browser, once, for exactly the plan shown; there is nothing to type.
- Was: Gemmein picks up a collection's fields from the records you write in Development.
  Now: Every community, shared and direct collection declares its fields in gemmein/collections/.json; nothing is guessed from test data.
- Was: Signing in on a second device signs the person out of the first.
  Now: Members stay signed in on up to 10 devices, each listed and signed out on its own; founders keep one dashboard session.
- Was: A plan-selling app needs its customer portal set up in Stripe and the link pasted on Payments.
  Now: Gemmein sets up Stripe's customer portal from your plans; g.subscriptions.manage() opens it. There is nothing to paste.
- Was: A chat AI tool runs only on the three hosts: OpenAI, Anthropic and Google.
  Now: A chat AI tool runs on OpenAI, Anthropic, Google or any endpoint that speaks the OpenAI Chat Completions format (provider openai-compatible: a base URL, a key and the endpoint's own model ids).
- Was: Going live drops localhost and every unverified domain for every key; before go-live a page works only on a listed domain or localhost.
  Now: The rule is per key: the Development app key works from any secure (https) address and from localhost, before and after go-live, with nothing to list; the Live app key works only on verified domains.
- Was: Live apps pay one plan whose price steps from $50 up to $150 a month with the previous month's active people.
  Now: Each Live app pays a flat price for its tier: Launch $10, Live $40 or Growing $100 a month (or $100, $400, $1,000 a year); past 15,000 people, talk to Gemmein.