@gemmein/sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -12,6 +12,215 @@ the same release.
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-09-08
+
+### The mobile surface, and the engine behind it (engine 0.11.0, sdk 0.10.0, mcp 0.7.0, GemmeinSwift 0.10.0)
+
+### Added — the mobile surface: an Expo entry point and a Swift SDK (W10)
+
+- **`@gemmein/sdk/expo`** — a second entry point of the same package,
+  re-exporting the whole core surface with a phone's answers filled in.
+  `createExpoGemmein(options, modules)` presets four of them and every one
+  stays overridable: `SecureStoreTokenStore` (the session in the iOS Keychain
+  / Android Keystore via `expo-secure-store`, keyed per app key exactly as
+  `BrowserTokenStore` keys `localStorage`, asked for with
+  `WHEN_UNLOCKED_THIS_DEVICE_ONLY` so a session cannot survive an iCloud
+  restore onto a device the person never had), `appStateVisibility()` (the
+  `watch()` visibility hook answered by React Native's `AppState`; only
+  "active" counts as in front of the person), and `expoFetch()` (`expo/fetch`,
+  because React Native's own fetch is XHR-backed and cannot give a streaming
+  body — which is what `ai.chat({ stream })` and `ai.run({ stream })` return).
+  Expo, `expo-secure-store`, `expo-file-system` and `react-native` are
+  OPTIONAL peer dependencies; nothing is imported from them at module load.
+- **Four options on the client, for any platform.** `fetch` — every request
+  the client makes goes through it, including the S3 upload leg and both AI
+  streams; the default reads `globalThis.fetch` at CALL time, so a polyfill
+  installed after construction still counts. `visibility`
+  (`{ isHidden, onChange }`) — where `watch()` learns the app went to the
+  background; absent, it is `document.visibilityState`, unchanged. `platform`
+  — a tag appended to `x-client-info` (cleaned and capped at 64 characters
+  here, so it cannot arrive truncated and attribute nothing). `tokenStore` as
+  before. A browser that passes none behaves exactly as it did.
+- **`UploadInput`** — `collection.upload()` now names what it takes:
+  `Blob | File | { uri, name?, type?, size? }`. The `File` check is guarded
+  with `typeof File !== "undefined"` (in React Native the bare form is a
+  `ReferenceError`, not a `false`), and a picker part is read for name, type
+  and size and appended to `FormData` as it is. Through
+  `@gemmein/sdk/expo` the picker part is converted first (see below).
+- **`CurrentUser.storeAccountToken`** — an opaque per-person id for the app
+  stores, minted lazily by the engine and returned by
+  `auth.currentUser()`. Hand it to RevenueCat as the app user id (or to Apple
+  as `appAccountToken`, Google as `obfuscatedExternalAccountId`), and a store
+  webhook resolves to exactly one person through a relay's `person_token`
+  without your app key or the person's email ever entering a third party's
+  ledger. Absent, not null, when nobody is signed in.
+- **`token_too_large`** — `SecureStoreTokenStore` refuses a session value over
+  the secure store's own size limit here, with a `GemmeinError`, rather than
+  by a native throw on a phone you cannot see.
+- **`GemmeinSwift` is the sibling surface** — the Swift SDK (SwiftPM, iOS 17+,
+  version 0.9.0 in the tree) speaks the same HTTP contract with the same
+  method names in Swift idiom, and the two travel together: a check holds
+  every Swift client class, and the Expo entry's re-exports, to the JS SDK's
+  own method registry, and resolves every method to a route the engine
+  serves. The SDK parity law — every SDK surface is the same — is a test, not
+  a habit.
+
+### Added — the engine behind it (engine 0.11.0)
+
+- **`GET /auth/current-user` answers `storeAccountToken`** — an opaque uuid,
+  unique per person, minted on first ask and correlated to nothing else.
+- **A relay receiver can name the person by id or by store token.** The
+  receiver map takes `person_id` and `person_token` beside `person_email`,
+  exactly one per map. `person_email` still creates the person when they are
+  new; the two lookups are read-only, and a value matching nobody keeps the
+  event and reports `person_not_found`, naming the key that was tried and
+  never its value. The first relay TEMPLATES ship with it: RevenueCat (app
+  stores), as THREE definitions, one webhook each — purchase
+  (`INITIAL_PURCHASE` / `RENEWAL` / `NON_RENEWING_PURCHASE`, narrowed in
+  RevenueCat's own console) → `fulfil_product`; `EXPIRATION` →
+  `revoke_access`; `CANCELLATION` → `revoke_access`. The two that TAKE access
+  away carry their own `when` guard, so a purchase posted to one of those URLs
+  by mistake can never revoke what it paid for; a trigger matches one exact
+  value per field, which is why they are two and not one. Idempotent on the
+  event id.
+- **Sign-in sends are counted and watched, never capped.** A per-app,
+  per-environment daily counter of ACCEPTED sign-in starts, shown on the Usage
+  page ("Sign-in emails · today · this month"), and a founder alert
+  `signin_surge` when a day passes max(1,000, 10× the app's trailing 7-day
+  mean). No new refusal: the two abuse bounds are the two that always
+  existed — 3 per address and 20 per IP per app, each per 15 minutes — and
+  growth is never capped.
+- **The pricing unit is monthly ACTIVE people.** A person counts once in a
+  month, on their first authenticated request of a UTC day, on web and mobile
+  alike — polling counts, anonymous never does, account members never do.
+  A new `active_people_daily` table is the one source for the Usage dial, the
+  people ceiling and the bill; the unit used to be derived from sign-in audit
+  rows, which counted sign-ins rather than use. Every surface says "active
+  people" where it said "verified people".
+- **An AI tool may be defined before its provider key.** Saving a tool no
+  longer answers `provider_not_configured`; the tool is listed as waiting on a
+  key (`providerConfigured`) and the console says so, and a RUN still answers
+  `409 ai_not_configured` until a key is pasted, before a single credit moves.
+- **One accepted-session hook, and both doors run it.** Everything that treats
+  a bearer token's holder as one of this app's people — the account-role
+  enrichment and the active-person write — now runs PAST the app/environment
+  match check, in `AuthContextBuilder`'s accepted-session hook rather than in
+  the session validator, so a request refused `401 auth_expired` leaves no
+  trace on anyone's bill. `POST /server/verify-session` runs the SAME hook: a
+  session verified by your own compute is an authenticated request by that
+  person too. Two consequences you can see: **`verifySession()` returns the
+  EFFECTIVE role** — account membership (owner/admin) wins over the stored
+  one, so a founder verifying their own session reads `owner` and not the
+  `member` their row was born with — and a person whose only authenticated
+  traffic goes through your compute is counted as active, like any other.
+  `GET /server/people/:id/holdings` answers with the same effective role: one
+  person has one role, whichever door asked for it.
+- Four migrations ship with this engine — `2026-09-08a` (the store token),
+  `08b` (the sign-in counter), `08c` (the `signin_surge` alert kind) and `08d`
+  (`active_people_daily`) — all additive, and NOT YET APPLIED to production:
+  they are applied before the images, never after.
+
+### Fixed — three contract gaps found by driving the Expo reference app (W10 row 9)
+
+- **A transport failure is now typed.** A request that never reaches Gemmein
+  — connection refused, no DNS, no Wi-Fi, an `apiUrl` pointing at nothing —
+  used to come out as whatever the fetch implementation threw (a `TypeError`
+  in a browser and on Expo's fetch), so an app branching on `err.code` got
+  `undefined` there and nowhere else. Every request the client makes now
+  answers `GemmeinError` `network_unreachable`, status 0, its message naming
+  the host and `err.cause` carrying the transport's own error. A call
+  cancelled with `{ signal }` still comes out as an `AbortError` — cancelling
+  is not a failure to reach anything.
+- **`GemmeinServer` has the same seam, and the same answer.** The server
+  client takes a `fetch` option (`gemmeinServer({ secretKey, fetch })`) and
+  every call it makes goes through it, so a transport failure on the server
+  rail is a `GemmeinError` `network_unreachable` (status 0, `err.cause`
+  carrying the transport's own error) and never a raw `TypeError` either. One
+  seam, both rails — the parity law applied to the thing underneath.
+- **`@gemmein/sdk/expo` accepts the picker's `{ uri, name, type, size }`.**
+  `expo/fetch`, which the Expo entry hands the client, refuses that part
+  (`Unsupported FormDataPart implementation`); `createExpoGemmein` now turns
+  it into an `expo-file-system` `File` before `upload()` sees it. Without
+  `expo-file-system` installed the call is refused here, with
+  `upload_input_unsupported` and a sentence, instead of crashing inside
+  FormData.
+- **`auth.logout()` is idempotent.** A `401 auth_expired` — the owner already
+  signed this person out everywhere — resolves rather than throwing, because
+  the session being gone is the outcome logout asked for. Every other failure
+  still throws, and the token store is cleared either way.
+
+The same three land in the Swift SDK (`GemmeinSwift`) in this commit: the SDK
+parity law — every SDK surface is the same.
+
+### Changed — a token store that cannot keep the session says so (W10 rows 9c, 15a)
+
+- **`tokenStore.set()` throws `secure_store_unavailable`.** Found by driving
+  the Swift reference app on an unsigned simulator build, where an app with
+  no `application-identifier` entitlement has no keychain access group and
+  every write is refused: the store swallowed it, so the app signed in,
+  stored nothing, and reported itself signed out one line later with nothing
+  anywhere saying why. `SecureStoreTokenStore.set` (`@gemmein/sdk/expo`) now
+  throws `GemmeinError` `secure_store_unavailable`, status 0, when
+  `expo-secure-store` cannot be resolved or refuses the write, with the
+  device's own throw on `err.cause`; `auth.verifyEmailCode()` carries it to
+  the caller. `get()` and `clear()` are unchanged and stay lenient — an
+  unreadable store means signed out, which every app already handles, and a
+  crash at launch is worse than a sign-in screen. The existing
+  `token_too_large` refusal is unchanged.
+- **What to do about it.** The session is real either way — the server minted
+  it — so an app that would rather run than stop can catch this one code and
+  build its client with a `MemoryTokenStore`: sign-in works, and ends with
+  the process. `MemoryTokenStore` never throws.
+- The same law lands in `GemmeinSwift`: the `TokenStore` protocol's `set` is
+  `throws`, `KeychainTokenStore.set` carries the OSStatus and
+  `SecCopyErrorMessageString`'s words for it out in the sentence, and
+  `MemoryTokenStore.set` never throws.
+- **`BrowserTokenStore.set()` throws it too — the law is all three stores
+  (row 15a).** A browser that refuses the `localStorage` write — Safari's
+  private mode past its quota, a browser set to block site data, a sandboxed
+  iframe whose access throws — used to be swallowed with the same silence the
+  two mobile stores were fixed for: the app signed in, stored nothing, and
+  reported itself signed out on the next reload. It now throws `GemmeinError`
+  `secure_store_unavailable`, status 0, with the browser's own error on
+  `err.cause` and the fix in the message; `get()` and `clear()` stay lenient.
+  Every surface that named the two mobile stores now says all three.
+  **ACTION REQUIRED for a web app that relied on the silence:** an app that
+  ran on with a session it could not persist — a kiosk, an embedded iframe, a
+  private-mode visitor — must catch `secure_store_unavailable` around
+  `auth.verifyEmailCode()` and rebuild its client with a `MemoryTokenStore`,
+  or pass one from the start. An app in an ordinary browser tab sees no
+  difference: nothing that stored the token before throws now.
+
+## [0.9.0] — 2026-09-07
+
+### Keys that know what they are, production sync, and AI tools defined on the server (engine 0.10.0, sdk 0.9.0, mcp 0.6.0)
+
+- **`g.ai.run(tool, inputs, { stream? })` / `g.ai.runText(tool, inputs)`** — call a
+  named AI tool with inputs only; the server composes the provider request
+  from the tool's own instructions and template, gates it, spends its
+  credits and streams the answer back in the provider's own shape.
+  Refusals: `invalid_inputs` (400), `tool_incomplete` (409), plus the tool
+  codes `g.ai.chat` already answered.
+- **`g.ai.calls()`** — the signed-in person's own AI calls, newest first,
+  keyset-paged (`AiCallRecord`): tool, provider, model, tokens, credits,
+  outcome, latency, and the prompt and answer where the tool keeps them.
+- **Raw calls are off by default.** `g.ai.chat(body)` answers
+  `403 raw_calls_off` unless the owner switches raw calls on for that
+  provider's key on the AI tools page. Migration note: an app built on
+  `g.ai.chat` needs that switch, or a named tool through `g.ai.run`.
+- **Server keys cannot sign in as the account owner or admin.**
+  `gemmeinServer(sk).testSession(email)` refuses those two emails with
+  `scope_denied`; test people sign in as before. Linking and dev sync use
+  the app's CLI key (`sk_cli_…`, Setup page); production sync uses a
+  one-hour Sync key (`sk_sync_…`). `secret_key_expired` (403) names an
+  expired sync key's instant.
+- CLI: `npx gemmein sync` links with ONE paste (the CLI key); `npx gemmein
+  sync --live` carries relays and AI tools into production behind a sync
+  key and the typed word `live`, never deletes, asks before replacing a
+  row edited in the dashboard (`--overwrite`). A relay's name is fixed once
+  created. Tool files gain `kind`, `instructions`, `promptTemplate`,
+  `inputs`, `recordCalls`.
+
 ## [0.8.0] — 2026-09-05
 
 ### Products are provider-neutral (engine 0.9.0, sdk 0.8.0, mcp 0.5.0)

package/README.md

@@ -1,6 +1,6 @@
 # @gemmein/sdk
 
-The secure backend for AI-built apps: passwordless login, safe data storage, and Stripe-driven payment flips — with the unsafe paths removed by design. No SQL, no security-rules language, no server to configure.
+The secure backend for AI-built apps: passwordless login, safe data storage, payments, credits and an AI route — with the unsafe paths removed by design. No SQL, no security-rules language, no server to configure. Web, Expo/React Native, and Swift, on one contract.
 
 ## Step 0 — get your app key
 
@@ -30,10 +30,14 @@ await g.collection("tasks").create({ title: "Buy milk", done: false })
 const { records } = await g.collection("tasks").list()
 ```
 
-The client has two layers: **your collections** (`g.collection("tasks")` — your app's own data model) and the **business primitives Gemmein runs for you** (`g.auth`, `g.subscriptions`, `g.payments`, `g.account` — self-service surfaces for the signed-in user; managing *other* people's users, subscriptions, and records happens in the owner's dashboard, on purpose).
+The client has two layers: **your collections** (`g.collection("tasks")` — your app's own data model) and the **business primitives Gemmein runs for you** (`g.auth`, `g.subscriptions`, `g.payments`, `g.purchases`, `g.credits`, `g.ai`, `g.files`, `g.account` — self-service surfaces for the signed-in user; managing *other* people's users, subscriptions, and records happens in the owner's dashboard, on purpose).
 
 Sessions persist across page reloads automatically (localStorage in browsers, memory elsewhere — override with `tokenStore` if you need custom persistence). One session per user: verifying a new code revokes that email's older sessions — a stale token throws `auth_expired` once, the SDK clears it, and a retry (or re-auth) recovers.
 
+A store that cannot **keep** the session says so: a browser that refuses the `localStorage` write (private mode past its quota, site data blocked, a sandboxed iframe) makes `verifyEmailCode()` throw `secure_store_unavailable` rather than hand back a session the next reload will lose. Reads and clears stay lenient — an unreadable store means signed out. The session is real either way, so an app that would rather run than stop catches that one code and rebuilds its client with a `MemoryTokenStore`, which never throws.
+
+Two reference documents ship beside this one: **[`REFERENCE.md`](./REFERENCE.md)** — every method, signature and return shape — and **`llms.txt`**, the guide to paste into an AI tool. Both are in the package; the same material is at **[docs.gemmein.com](https://docs.gemmein.com)**.
+
 ## Auth
 
 ```js
@@ -56,6 +60,38 @@ await g.account.delete()
 
 Self-service erasure — the "delete my account" screen. Every app it **applies** to needs one (GDPR right to erasure; Apple 5.1.1(v) for any app with account creation). Server-side it's the full cascade: sessions revoked, the user's records and files deleted, their subscription row removed. Irreversible — put a real confirm in front of it.
 
+## Mobile — Expo and Swift
+
+A phone app is the same contract as a browser app: the public key identifies the app, the session authorises the person. Verified domains are a browser control — an app sends no `Origin`, so nothing is verified there; build as though any request could come from anywhere and let the session and the server's rules decide.
+
+**Expo / React Native.** `@gemmein/sdk/expo` is this same package, a second entry point that fills in the four seams a phone has — where the session lives, how "is the app in front?" is answered, which `fetch` carries the bytes, and what the client tag says. Peers install in the app, not in your monorepo: `npx expo install expo-secure-store expo-file-system`.
+
+```js
+import { createExpoGemmein } from "@gemmein/sdk/expo"
+import { AppState, Platform } from "react-native"
+
+export const g = createExpoGemmein({ appKey: "pk_live_..." }, { AppState, Platform })
+```
+
+Every module is optional — pass none and the entry resolves `expo-secure-store`, `react-native` and `expo/fetch` lazily on first use. The injectable keys are `SecureStore`, `AppState`, `Platform`, `FileSystem` and `fetch`; the client tag reads `expo-ios` / `expo-android` / `expo-web` when you pass `Platform`, and `expo` when you don't. `apiUrl` is an option on the client, so pointing the app at a local `gemmein dev` engine is one field: `createExpoGemmein({ appKey, apiUrl: "http://127.0.0.1:4545" }, { AppState, Platform })`.
+
+**Swift.** `GemmeinSwift` — iOS 17+ / macOS 14+, no dependencies, the same method names in Swift idiom. One line in `Package.swift`:
+
+```swift
+.package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.10.0")
+```
+
+**Store purchases, either way.** `currentUser()` carries `storeAccountToken` — an opaque per-person id. Hand it to RevenueCat as the app user id, and a store webhook resolves to exactly one person through a relay, without your app key or the person's email ever entering a third party's ledger.
+
+```js
+const me = await g.auth.currentUser()
+if (me.authenticated && me.storeAccountToken) {
+  await Purchases.configure({ apiKey: RC_KEY, appUserID: me.storeAccountToken })
+}
+```
+
+The whole mobile surface — the codes a phone meets, the store road, the two host facts for simulators — is at **[docs.gemmein.com/mobile](https://docs.gemmein.com/mobile)**.
+
 ## Storage
 
 Collections are created by the app owner in the dashboard (app.gemmein.com → data → "+ New collection") — the SDK can't create them. A 404 `unknown_collection` means it doesn't exist yet: ask the app owner to add it (one click) and pick its rule from the table below.
@@ -82,7 +118,7 @@ await tasks.delete("rec_abc123")
 
 // Images/files: presigned upload, returns a REFERENCE to store in a record
 const file = await tasks.upload(imageBlob, { name: "avatar.png" })
-// { id, ref, contentType, sizeBytes }   ref looks like "file:01K…"
+// { id, ref, contentType, sizeBytes }   ref looks like "file:<uuid>"
 await tasks.create({ title: "Profile", avatar: file.ref })
 
 // To show or download it — one call, whatever the collection:
@@ -197,26 +233,31 @@ Plan **limits** (note counts, feature caps, seat numbers) are your app's logic
 
 ### Selling things (one-off purchases)
 
-Plans are for subscriptions. To sell a **thing** — a poster, a beat, an ebook, a session — the owner adds **products** (name + Stripe Payment Link) on the same Payments page, plus a **receipts** collection (rule `addressed`). Then:
+Plans are for subscriptions. To sell a **thing** — a poster, a beat, an ebook, a session — the owner adds **products** on the same Payments page and sets **how each is sold**: via a Stripe Payment Link, via a **relay** (any provider whose webhook they map — GoCardless, Lemon Squeezy, Paddle, an app store through RevenueCat, a bank transfer), or **not yet** (the product is defined, its grants and credits known, no road wired).
 
 ```js
 // One product covering many items (license tiers over a catalog)? Name the
-// item — it's display text on the receipt, the PRICE always comes from the
-// product's Payment Link:
+// item — display text only; the PRICE always comes from the provider:
 await g.payments.buy("premium license", { item: "beat_37" })   // redirects
-
-// Fulfilment: the completed payment writes a receipt record ADDRESSED to
-// the buyer — only they (and the owner) can read it. Gate the download on
-// the receipt, never on the redirect coming back (redirects can be faked;
-// receipts can't — they come from Stripe's signed webhook):
-const { records } = await g.collection("receipts").list()
-const paid = records.find(r => r.data.product === "premium license" && r.data.status === "paid")
-if (paid) { /* unlock — paid.data.deliveryUrl holds the download when the owner set one */ }
+// "product_not_sellable" (409) = sold via a relay, or not yet: there is no
+// Payment Link to open. "unknown_product" (404) lists what the app sells.
+
+// Fulfilment: Gemmein records every completed payment itself, so the buyer's
+// proof does not live in your data. Gate on THIS, never on the redirect
+// coming back (redirects can be faked; the record comes from the provider's
+// signed webhook):
+const purchases = await g.purchases.mine()
+const paid = purchases.find(p => p.item === "premium license" && p.status === "paid")
+if (paid?.delivery?.type === "gemmein_file") {
+  const { url } = await g.files.link(paid.delivery.file, { intent: "download" })
+}
 ```
 
-Receipts carry `{ product, item?, status, amountTotal, currency, paidAt, deliveryUrl?, paymentRef }` in `.data` — `amountTotal` is minor units exactly as Stripe reported, and `paymentRef` is the Stripe payment id the refund flip matches on (read-only; you rarely need it). The owner fulfils orders by editing the receipt from their dashboard (`status: "shipped"`) — your app just reads it. Refunds happen in the owner's Stripe dashboard; if they forward `charge.refunded`, the receipt's status flips to `"refunded"`. A receipt is **app-owned** — its top-level `ownerUserId` is `null` (the webhook wrote it, not a user); it's the `audienceUserId` that scopes it to the buyer.
+Each purchase is `{ item, kind: "purchase" | "subscription", status: "paid" | "part_refunded" | "refunded", amountMinor, currency, refundedMinor, grants, paidAt, delivery? }`, newest first, refunds already applied — amounts are **minor units** (pence, cents) exactly as the provider reported them, so formatting is yours and nothing is rounded away. To sell a **file**, the owner attaches it on the product card: the purchase carries `delivery: { type: "gemmein_file", file }` and *is* the authorization, re-checked on every `g.files.link()` — a full refund cuts the download off the moment it lands. `delivery: { type: "external_url", url }` is a plain handover: Gemmein controls who is told, not who can use it.
+
+A **receipts** collection (rule `addressed`) is now **optional** — proof records for your own screens, nothing more. Financial truth is `g.purchases.mine()`, and it stays true if you rename or delete that collection.
 
-**No carts, no quantities** — one product per checkout, by design. A "cart" is N checkouts, or one bundled product the owner prices as a bundle. Don't build a cart UI that promises otherwise.
+**No carts, no quantities** — one product per checkout, by design. A "cart" is N checkouts, or one bundled product the owner prices as a bundle. Don't build a cart UI that promises otherwise. Digital access only: physical goods, shipping and inventory are out of scope. Full detail: **[docs.gemmein.com/payments](https://docs.gemmein.com/payments)**.
 
 ### Drafts on public collections
 
@@ -229,7 +270,24 @@ await notes.update(post.id, {}, { published: true })                     // now
 
 Read the current state back as a **top-level** field — `record.published` (a boolean), NOT `record.data.published` (same place as `id` and `updatedAt`, not inside your fields). Non-authors only ever receive published records, so you'll only ever see `false` on your own drafts — or on everything, as the owner. That's how you render an "unreleased" badge in an owner-only admin list.
 
-Never fake drafts with a `status` field + client-side filtering on a public collection — the data still reaches every reader's network tab. `published` is an option, not a data field; the server rejects it inside `data`.
+Never fake drafts with a `status` field + client-side filtering on a public collection — the data still reaches every reader's network tab. `published` is an option, not a data field; the server rejects it inside `data`. The **field** comes back on every record, whatever the rule: a private record reads `published: true`, and the option is not writable there.
+
+## Credits
+
+A **credit** is a quantity the signed-in person holds and your product spends — a pack they bought (a product with "Grants credits"), a comp the owner gave them, a relay's grant. `g.credits.balance()` is the number **right now**, server-resolved, so your meter never does client-side arithmetic on a balance that refuses at zero; a spend from your own server is `gemmeinServer(sk).spendCredits(personId, { amount, reason, key })`, one conditional update floored at 0, and `402 credits_exhausted` carries the balance. There is deliberately no client write path. Full detail: **[REFERENCE.md](./REFERENCE.md)** → *Credits*, and **[docs.gemmein.com/credits](https://docs.gemmein.com/credits)**.
+
+## AI
+
+`g.ai.run(tool, inputs)` calls a **named AI tool** the owner defined — the server composes the provider request from the tool's own instructions and template (never the browser), gates it, spends the tool's credits and streams the provider's own answer back; `g.ai.runText(tool, inputs)` is the same call collected to one string, and `g.ai.calls()` is the signed-in person's own history. The provider key lives with Gemmein and never reaches the browser. `g.ai.chat(body)` is the raw path — the provider's own request body, forwarded — and it is **off by default** (`403 raw_calls_off`) until the owner switches raw calls on for that key. Full detail: **[REFERENCE.md](./REFERENCE.md)** → *AI*, and **[docs.gemmein.com/ai](https://docs.gemmein.com/ai)**.
+
+```js
+const summary = await g.ai.runText("summarise", { text })
+const { balance } = await g.credits.balance()
+```
+
+## Relays
+
+A **relay** is one trigger — another provider's webhook arriving, a clock, a record changing — and one to ten of Gemmein's own typed actions, run in order: grant or revoke access, fulfil or refund a product, grant credits, write a record, email a person, call a URL. The owner writes `gemmein/relays/<name>.json` (or picks a template in the console); Gemmein verifies the signature, maps the body to named fields, and runs the actions. Nothing computes inside one — compute lives on your host, behind `call_url`. That is the road an app store purchase travels, and the road a payment provider other than Stripe travels. It is configuration, not SDK surface — your app only ever reads the result (`g.purchases.mine()`, `g.credits.balance()`, a gated collection succeeding). Full detail: **[REFERENCE.md](./REFERENCE.md)** → *Relays*, and **[docs.gemmein.com/relays](https://docs.gemmein.com/relays)**.
 
 ## Server-side (API routes, cron jobs)
 
@@ -244,7 +302,7 @@ const tasks = await server.collection("tasks").list()
 await server.collection("tasks").update("rec_abc123", { done: true })
 ```
 
-Secret keys can only `get`/`list`/`update` the collections you scoped them to — no creates, no deletes, no auth or management access. Never put an `sk_` key in browser code (the SDK throws if you try).
+On collections a secret key can only `get`/`list`/`update` the ones you scoped it to — no creates, no deletes. Beyond that it opens **the gate**, for code of yours running on your own host: `verifySession(token)` turns a browser session into the person and what they hold, `holdings(personId)` answers that on its own, `grantAccess` / `revokeAccess` move one grant (a grant ends once — a second revoke is `409 already_revoked`), `spendCredits` takes credits with a reason, `invitePerson(email)` creates or fetches a person by address, and `notify(personId, …)` emails one of your app's own people. Each is a capability ticked on the key when it is minted; an untick is `403 capability_required`. No management access, ever. Never put an `sk_` key in browser code (the SDK throws if you try).
 
 ## Errors
 
@@ -283,6 +341,9 @@ try {
 | `forbidden` | 403 | The rules refused this — a permission your user doesn't have. **Never retry**: the same call will always be refused. Fix the approach (wrong collection rule, non-admin writing to `admin_write`, secret key out of scope) or show `err.message`. |
 | `entitlement_required` | 403 | Signed in, but not on a plan (or holding a product) this collection is unlocked by. `err.requires` carries that plan's key (`access:pro` for a plan named pro). The one 403 that succeeds later: show your upgrade screen, send them to checkout, retry after they hold it. |
 | `denied` | 429 / 401 | The generic refusal for everything retriable or fixable: a rate limit (429 — carries `resetAt`, wait and retry) or a missing sign-in (401 — sign in first via `g.auth.sendEmailCode`). Distinguish by HTTP status; show `err.message`, which reads correctly for each. |
+| `invalid_collection_name` | 0 (client-side) | `g.collection(name)` was given a name outside the grammar — lowercase letters, numbers and underscores, starting with a letter, 2-63 characters. Thrown before a request exists. |
+| `secure_store_unavailable` | 0 (client-side) | The token store could not KEEP the session — a browser refusing the `localStorage` write, `expo-secure-store` absent or refused, a Keychain that said no. `err.cause` carries the store's own error. Pass a `tokenStore` (a `MemoryTokenStore` keeps the session for the life of the process). |
+| `network_unreachable` | 0 (client-side) | The request never reached Gemmein — no connection, a host that doesn't resolve, an `apiUrl` pointing at nothing. The message names the host; `err.cause` carries the transport's error. Branch on it separately from a refusal. |
 
 **Branching on error codes:** switch on the *specific named* codes above. The one rule that matters: `forbidden` means stop — retrying can never succeed; `denied` means the request could work later (wait for `resetAt` on 429, sign in on 401). Only rate-limit `denied` carries `resetAt` — that's the reliable signal for a retry-after.
 
@@ -292,7 +353,9 @@ try {
 |--------|------------|----------------|
 | `pk_test_...` | Development | Frontend code — safe to expose |
 | `pk_live_...` | Production | Frontend code — safe to expose |
-| `sk_dev_...` / `sk_live_...` | Dev / Prod | Server env vars only |
+| `sk_dev_...` / `sk_live_...` | Dev / Prod | Server env vars only — runs your app; never links or syncs |
+| `sk_cli_...` | Development | The CLI key, shown on Setup: what `gemmein sync` and `gemmein go-live` act with. Lives in `gemmein/.data/`, never in git |
+| `sk_sync_...` | Production | A one-hour sync key (Secret keys → production): `gemmein sync --live` carries relays and AI tools into production. Pasted, used, never saved |
 
 Environments are fully isolated: different data, different users, different collections.