@gemmein/sdk 0.8.0 → 0.10.0

package/REFERENCE.md

@@ -1,6 +1,8 @@
 # Gemmein SDK — API Reference
 
-Complete surface of `@gemmein/sdk`, generated from the type definitions.
+Complete surface of `@gemmein/sdk`, generated from the type definitions —
+with, beside each JavaScript method, the `GemmeinSwift` signature and return
+type for the same method, and everything `@gemmein/sdk/expo` adds.
 This is the **reference** (every method, signature, return shape, error);
 `llms.txt` is the **guide** (how the model works and the safe patterns). Both
 are needed. Draft — feeds docs.gemmein.com.
@@ -16,9 +18,45 @@ const g = gemmein("pk_...");        // browser: your public app key (domain-lock
 
 ### `gemmein(appKey, options?) → Gemmein`
 The browser client. `appKey` is your public `pk_...` key. `options` (optional):
-`{ apiUrl?: string, tokenStore?: TokenStore }`. Throws `GemmeinError`
+`{ apiUrl?: string, tokenStore?: TokenStore, fetch?: typeof fetch, visibility?: VisibilityHook, platform?: string }`.
+Throws `GemmeinError`
 (`missing_app_key` / `invalid_app_key`) if the key is absent or an `sk_`.
 
+The last three are what a non-browser runtime needs and a browser never passes.
+`fetch` is used for **every** request this client makes, in place of
+`globalThis.fetch`. `visibility`
+(`{ isHidden(): boolean; onChange(cb: () => void): () => void }`) is where
+`watch()` learns the app went to the background, in place of
+`document.visibilityState`; `onChange` returns its own unsubscribe. `platform`
+is appended to the `x-client-info` header — `gemmein-sdk/<version> expo-ios` —
+cleaned and capped to the 64 characters the usage ledger stores.
+
+On Expo, `createExpoGemmein` from `@gemmein/sdk/expo` fills those three in for
+a phone, and turns `upload()`'s picker shape into bytes Expo's fetch will
+send. Every export that entry adds is in **Expo** below.
+
+### `Gemmein(appKey:) → GemmeinSwift.Gemmein`
+The Swift package, for iOS 17+ and macOS 14+, with no dependencies:
+`.package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.10.0")`.
+The same HTTP contract and the same method names as `@gemmein/sdk`, in Swift
+idiom — `g.auth`, `g.collection(_:)`, `g.files`, `g.subscriptions`,
+`g.payments`, `g.purchases`, `g.account`, `g.credits`, `g.ai`, and
+`GemmeinServer` for Swift that runs on a server.
+
+```swift
+let g = try Gemmein(appKey: "pk_live_…")   // KeychainTokenStore by default
+
+try await g.auth.sendEmailCode(email)
+_ = try await g.auth.verifyEmailCode(email: email, code: code)
+let page = try await g.collection("notes").list(ListOptions(limit: 20))
+let me = try await g.auth.currentUser()    // .storeAccountToken for RevenueCat
+```
+
+An `sk_` key is refused here, as in the browser. Every Swift signature sits
+beside its JavaScript twin in the sections below, under **Swift**; the client's
+own initialiser, the shapes that differ, and the session store are in **Swift —
+the package**.
+
 ### `gemmeinServer(secretKey, options?) → GemmeinServer`
 Server-only client for a `sk_...` secret key — **never ship this to the
 browser.** `options` (optional): `{ apiUrl?: string }` — **the option is
@@ -49,12 +87,32 @@ happens in the owner's dashboard, deliberately not in this SDK.
 | `currentUser` | `()` | `Promise<CurrentUser>` — **never throws** for session state; safe on load |
 | `logout` | `()` | `Promise<void>` — revokes the server session **(the method is `logout`, not `signOut`)** |
 
+
+**Swift.** `GemmeinSwift` names the same four methods, with Swift's argument
+labels. Everything that leaves the device is `async throws` and throws
+`GemmeinError`.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `sendEmailCode(_:)` | `func sendEmailCode(_ email: String) async throws` | `Void` |
+| `verifyEmailCode(email:code:)` | `func verifyEmailCode(email: String, code: String) async throws -> AuthSession` | `AuthSession { token: String, expiresAt: String, user: AuthUser }` |
+| `currentUser()` | `func currentUser() async throws -> CurrentUser` | `CurrentUser { authenticated: Bool, userId: String?, email: String?, storeAccountToken: String? }` — one struct with optionals where JS has a union: read `authenticated` first, then the rest |
+| `logout()` | `func logout() async throws` | `Void` — idempotent |
+
 ```ts
 type AuthSession = { token: string; expiresAt: string; user: { id: string; email: string } };
 type CurrentUser =
-  | { authenticated: true;  userId: string; email: string }   // note: userId, NOT id
-  | { authenticated: false; userId?: undefined; email?: undefined };
+  | { authenticated: true;  userId: string; email: string; storeAccountToken?: string | null }   // note: userId, NOT id
+  | { authenticated: false; userId?: undefined; email?: undefined; storeAccountToken?: undefined };
 ```
+`storeAccountToken` is the opaque per-person name to hand a store — RevenueCat's
+app user id, Apple's `appAccountToken`, Google's `obfuscatedExternalAccountId`.
+It is minted on the first `currentUser()` call, stable for the life of the
+person, correlated to nothing, and gone when they are erased. Hand a store
+that, never `userId` and never the address: a value inside a third party's
+ledger is outside the erasure cascade. An engine that does not carry one leaves
+the field absent — read that as "not carried", never as "no account". See
+**Mobile** below.
 `verifyEmailCode` resolves the **session** (`user.id`, nested). `currentUser`
 resolves the **identity** (`userId`, flat). Use `currentUser()` for who's
 signed in. Sessions are one-per-user: verifying a new code revokes older ones.
@@ -72,6 +130,11 @@ screen covers all three.
 |--------|-----------|---------|
 | `delete` | `()` | `Promise<unknown>` — erases the signed-in user, clears the stored token |
 
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `delete()` | `@discardableResult func delete() async throws -> JSONValue?` | `JSONValue?` — the server's body as a `JSONValue?` where JS has `unknown`; `@discardableResult`, so ignoring it is legal |
+
 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, records and files
@@ -103,15 +166,46 @@ certain the collection exists yet.
 | `delete` | `(id: string)` | `Promise<void>` |
 | `upload` | `(file: Blob \| File, options?: { name?: string; contentType?: string; for?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
 
+
+**Swift.** The same seven methods. Three shapes differ on purpose: a record
+body is `[String: JSONValue]` (a literal needs no ceremony —
+`["title": "Ran", "done": false]` — a variable needs its case,
+`["title": .string(typed)]`); `upload` takes `Data`, not a `Blob`; and `watch`
+is not `async` — it hands back a `Watcher` you end with `stop()`.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `create(_:key:for:published:)` | `@discardableResult func create(_ data: [String: JSONValue], key: String? = nil, for recipient: String? = nil, published: Bool? = nil) async throws -> GemmeinRecord` | `GemmeinRecord` |
+| `list(_:)` | `func list(_ options: ListOptions = ListOptions()) async throws -> ListResult` | `ListResult { records: [GemmeinRecord], cursor: String?, hasMore: Bool, deleted: [String], watermark: String? }` |
+| `watch(every:where:search:limit:onChange:)` | `func watch(every: TimeInterval? = nil, where filter: [String: JSONValue]? = nil, search: String? = nil, limit: Int? = nil, onChange: @escaping @Sendable (WatchDelta) -> Void) -> Watcher` | `Watcher` — **not `async`**; `watcher.stop()` ends it. `WatchDelta { records: [GemmeinRecord], deleted: [String], initial: Bool }` |
+| `get(_:expand:)` | `func get(_ id: String, expand: [String] = []) async throws -> GemmeinRecord` | `GemmeinRecord` |
+| `update(_:_:ifVersion:published:)` | `@discardableResult func update(_ id: String, _ data: [String: JSONValue], ifVersion: Int? = nil, published: Bool? = nil) async throws -> GemmeinRecord` | `GemmeinRecord` |
+| `delete(_:)` | `func delete(_ id: String) async throws` | `Void` |
+| `upload(_:name:contentType:for:)` | `func upload(_ data: Data, name: String = "upload", contentType: String = "", for recipient: String? = nil) async throws -> UploadedFile` | `UploadedFile { id: String, ref: String, contentType: String, sizeBytes: Int }` — `ref` is `file:<uuid>` |
+
+`ListOptions(limit:sort:where:cursor:search:expand:since:)` — every argument
+optional, `sort` is `ListSort` (`.newest`, `.oldest`, `.updated`), and `where`
+keeps the label `where`, binding a `[String: JSONValue]`. `GemmeinRecord`
+carries `id`, `data: [String: JSONValue]`, `createdAt`, `updatedAt`,
+`ownerUserId: String?`, `collectionId`, `appId`, `environmentId`,
+`version: Int`, `key: String?`, `audienceUserId: String?`, `published: Bool`,
+`expand: [String: GemmeinRecord?]` and `existing: Bool?` — your fields live
+under `data`, read as `note.data["title"]?.string`.
+
 ### Files
 
-`upload()` returns a **reference** (`file:01K…`), not a URL. Store the reference
+`upload()` returns a **reference** (`file:<uuid>`), not a URL. Store the reference
 in your record — it never expires and grants nothing on its own.
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
 | `g.files.link` | `(ref: FileRef \| string, options?: { intent?: "inline" \| "download" })` | `Promise<{ ref, url, expiresAt?, contentType, sizeBytes?, name? }>` |
 
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `g.files.link(_:intent:)` | `func link(_ ref: String, intent: LinkIntent? = nil) async throws -> FileLink` | `FileLink { ref: String, url: String, expiresAt: String?, contentType: String, sizeBytes: Int?, name: String? }` — **`url` is a `String`**, not a `URL`: pass it through `URL(string:)` before handing it to `AsyncImage`. `intent` is `.inline` or `.download` |
+
 ```ts
 const { ref } = await g.collection("films").upload(file)
 await g.collection("films").create({ title, poster: ref })
@@ -172,7 +266,7 @@ type GemmeinRecord<T> = {
   version: number;             // +1 per update; pass as { ifVersion } to guard concurrent edits
   key?: string;                // the create-if-absent key, when one was used
   audienceUserId?: string;     // recipient on addressed/direct collections (server-stamped)
-  published: boolean;          // top-level, not under .data; only meaningful on public rules
+  published: boolean;          // top-level, not under .data; on EVERY record — a private record reads true
   expand?: Record<string, GemmeinRecord | null>;  // filled by list/get { expand: [...] }
   existing?: true;             // present only when a keyed create returned YOUR existing record
 };
@@ -201,7 +295,9 @@ retry doubles as the lookup: there is no separate get-by-key call — re-issue
 the same `create()` with the same key to fetch your own record (it counts
 as a write; a re-fetch idiom, not a read path). `for` =
 recipient id on `addressed`/`direct`. `published: false` = draft on a public
-rule. `ifVersion` = optimistic concurrency. Atomic counters go in *value*
+rule; the OPTION is refused anywhere else (400 `invalid_publish`), while the
+FIELD comes back on every record — a private record reads `published: true`,
+and it is not writable there. `ifVersion` = optimistic concurrency. Atomic counters go in *value*
 position: `update(id, { stock: { decrement: 1, floor: 0 } })`. `expand` throws
 on `private`/`public_read`/`admin_write` (no link shape) — join in memory there.
 `since` fixes the order (oldest change first) — pairing it with `sort` is a 400
@@ -233,6 +329,17 @@ Never hand-roll a polling loop; this is the sanctioned one.
 | `payments.buy` | `(product: string, options?: { item?: string })` | `Promise<{ url: string; product: string; item?: string }>` — **navigates the browser to Stripe** and resolves the url |
 | `purchases.mine` | `()` | `Promise<Purchase[]>` — the array itself (not wrapped): `{ item, kind, amountMinor, currency, refundedMinor, status, grants, paidAt, delivery? }` — gate one-off fulfilment on this, never the redirect |
 
+
+**Swift.** Nothing navigates: `checkout` and `buy` answer a url and the app
+opens it (`openURL`, `SFSafariViewController`).
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `g.subscriptions.mine()` | `func mine() async throws -> Subscription?` | `Subscription? { plan: String, status: String }` — `nil` when they never paid |
+| `g.subscriptions.checkout(plan:)` | `func checkout(plan: String? = nil) async throws -> CheckoutSession` | `CheckoutSession { url: String, plan: String }` |
+| `g.payments.buy(_:item:)` | `func buy(_ product: String, item: String? = nil) async throws -> PaymentSession` | `PaymentSession { url: String, product: String, item: String? }` |
+| `g.purchases.mine()` | `func mine() async throws -> [Purchase]` | `[Purchase]` — `item`, `kind`, `amountMinor: Int?`, `currency: String?`, `refundedMinor: Int`, `status`, `grants: [String]`, `paidAt`, `delivery: Purchase.Delivery?` (`.gemmeinFile(String)` or `.externalURL(String)` — an enum where JS has a tagged object) |
+
 Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 `buy` self-navigate via `window.location` — just `await` them on the click;
 don't also redirect to the returned `url`, and never build a Stripe URL
@@ -278,6 +385,14 @@ honestly, not hidden.)
   carries a footer naming why it arrived; replies land in the owner's Inbox
   as a thread (`threadId`), and `replyRail` states honestly whether
   reply-by-email is on. Every send is on the record.
+- **Your domain, or nothing.** `notify()` sends only from your verified
+  sender domain. Until one is verified on the Domains page the send is
+  refused `409 sender_domain_required` — nothing leaves, nothing is
+  recorded, no cap is spent, and the same `key` sends once you verify. If
+  the provider refuses that address at send time you get `502 send_failed`
+  and can retry; the email is never re-sent from a Gemmein address. Sign-in
+  codes are the one email Gemmein sends on your behalf before a domain is
+  verified, as `<App name> (via Gemmein)`.
 
 ---
 
@@ -297,6 +412,12 @@ the message), never partly. No expiry. No per-token pricing.
 | `gemmeinServer(sk).spendCredits` | `(personId, { amount?: number; reason: string; key?: string })` | `Promise<{ ok: true; spent: number; deduped: boolean; balance: { before: number; after: number }; event: { id, reason, actor } }>` — `amount` defaults to 1 (1..10,000); `reason` ≤ 200 chars is what the owner reads on the person's ledger; `key` makes the spend at-most-once per person (a repeat answers `deduped: true`, `spent: 0`, the same `event`, and moves nothing; one key reused for a second person charges that person). Needs **"Spend a person's credits"** ticked on the key (`403 capability_required` otherwise) |
 | `Holdings.credits` | — | `{ balance: number }` on `verifySession()` and `holdings()` from engine 0.8.0 (`null` from an older local engine) — one verify answers who, what they hold and how many |
 
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `g.credits.balance()` | `func balance() async throws -> Int` | **`Int`** — the balance itself, where JS answers `{ balance }`. Read it directly |
+| `gemmeinServer(sk).spendCredits` | `@discardableResult func spendCredits(_ personId: String, amount: Int? = nil, reason: String, key: String? = nil) async throws -> SpendCreditsResult` | `SpendCreditsResult { spent: Int, deduped: Bool, balanceBefore: Int, balanceAfter: Int, event: Event }` — two flat `Int`s where JS nests `balance: { before, after }` |
+
 Where credits come from, and where they go:
 
 - **A product with `grantsCredits`** (the "Grants credits" field on the
@@ -353,30 +474,99 @@ connected.
 
 ---
 
-## AI — `g.ai.chat` / `g.ai.text`
+## AI — `g.ai.run` / `g.ai.runText` / `g.ai.calls` (and the raw `g.ai.chat` / `g.ai.text`)
 
 Your app talks to **OpenAI, Anthropic or Google** through Gemmein, on the
 **owner's own provider key**, which never reaches the browser, through a
-**named AI tool** — a slug the owner prices in credits, pins a model or
-provider to, and gates behind an entitlement, from the dashboard's Tools
-page or a local `gemmein/ai/tools/<name>.json` file. Removing a tool is a
-step-up action, like removing a key. A call that names no
-`tool` runs as the **default tool**: one credit, the app's configured
-provider, any allowed model — every existing integration that never passed
-`tool` keeps working unchanged. The owner pastes each provider key once in
-the dashboard's Keys room; it is write-only from then on. The route
-forwards the provider's own request body as sent — minus the `provider`
-field, and for Google minus `model` and `stream`, which ride the URL — adds
-the provider's auth headers, `content-type` and `accept`, and passes the
-status and the bytes straight back — a stream stays a stream. It does not
-choose models, cache, summarise, moderate or reshape anything, and it is for
-the browser only: a server key is refused (`403 scope_denied`) — a server
-calls the provider directly.
+**named AI tool whose definition lives on the server** (W9.6): the
+instructions (system prompt), the prompt template, the inputs it accepts,
+the pinned model, the caps — beside the price in credits and the
+entitlement gate. The app sends a **name and inputs**; the server composes
+the provider request in the provider's own grammar, gates it, spends the
+tool's credits, runs it and streams the answer back. The owner prices and
+gates the tool on the dashboard's AI tools page; the implementation is
+written there too, or as a file at `gemmein/ai/tools/<name>.json` that
+`npx gemmein sync` carries (`--live` into production with a sync key). A
+file carries at least `label`, `provider` and `credits` (its name is the
+file name). On every sync the file's implementation (`provider`, `model`,
+`kind`, `instructions`, `promptTemplate`, `inputs`, `bounds`) applies; its
+commerce values (`label`, `credits`, `requires`, `enabled`, `recordCalls`)
+apply once, at creation — after that the dashboard owns them. In
+development, sync also writes a tool that exists only in the cloud back to
+`gemmein/ai/tools/` as a file; in production such a row is left as it is.
+A tool's name is fixed once created. Removing a tool is a step-up action, like
+removing a key.
+
+
+**Swift.** `AiResponse` stands where JS returns the fetch `Response`, and
+`run` / `runText` take the label **`inputs:`** —
+`runText("summary", inputs: ["text": .string(body)])`.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `run(_:inputs:stream:)` | `func run(_ tool: String, inputs: [String: JSONValue] = [:], stream: Bool = false) async throws -> AiResponse` | `AiResponse` — `stream` is a plain `Bool` argument, not an options object |
+| `runText(_:inputs:)` | `func runText(_ tool: String, inputs: [String: JSONValue] = [:]) async throws -> String` | `String` — the label is **`inputs:`** |
+| `calls(limit:before:)` | `func calls(limit: Int? = nil, before: String? = nil) async throws -> AiCallPage` | `AiCallPage { calls: [AiCallRecord], nextCursor: String? }` |
+| `chat(_:provider:tool:)` | `func chat(_ body: [String: JSONValue], provider: AiProvider? = nil, tool: String? = nil) async throws -> AiResponse` | `AiResponse` |
+| `text(_:provider:tool:)` | `func text(_ body: [String: JSONValue], provider: AiProvider? = nil, tool: String? = nil) async throws -> String` | `String` |
+
+`AiResponse` carries `status: Int`, `headers: [String: String]`, `ok: Bool`,
+`creditsRemaining: Int?`, `refunded: Bool`, `tool: String?`, `isFake: Bool`,
+`func data() async throws -> Data`, and two streams —
+`func lines() -> AsyncThrowingStream<String, Error>` and
+`func events() -> AsyncThrowingStream<String, Error>` (the SSE `data:`
+payloads). `AiProvider` is `.openai`, `.anthropic`, `.google`.
+
+**Raw calls are off by default.** `g.ai.chat(body)` — the browser sending
+the provider's own request body — answers `403 raw_calls_off` unless the
+owner switches **raw calls** on for that provider's key on the AI tools page. Behind the switch, the raw route is what it always was: the body is
+forwarded as sent (minus `provider`, and for Google minus `model` and
+`stream`, which ride the URL), the provider's own status and bytes pass
+straight back, a stream stays a stream, and a call that names no `tool`
+runs as the **default tool** (one credit, the configured provider, any
+allowed model). `gemmein dev` with no key keeps raw calls open — the fake
+answers and there is no switch locally. Both routes are for the browser
+only: a server key is refused (`403 scope_denied`) — a server calls the
+provider directly.
+
+**Every call lands on `ai_calls`**, the managed collection: who, which tool,
+kind, provider, model, tokens in/out (when the provider said), credits,
+outcome, refusal code, latency, when. The **prompt and answer** ride the row
+only when the owner switches *record calls* on for that tool — off by
+default. A person reads their own (`g.ai.calls()`), the owner reads by app
+in the back office, erasure removes a person's rows.
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
-| `ai.chat` | `(body: object, options?: { tool?: string; provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — the fetch `Response`, untouched: the provider's status, headers and body, streaming intact. A non-2xx from the provider is returned as-is (not thrown) — an answer carrying `x-gemmein-credits-remaining` passed the spend and is the provider's; a Gemmein refusal throws `GemmeinError` |
-| `ai.text` | `(body: object, options?: { tool?: string; provider?: …; signal?: AbortSignal })` | `Promise<string>` — a non-stream call collected to one string, whichever provider answered (openai `choices[0].message.content`; anthropic `content[].text` joined; google `candidates[0].content.parts[].text` joined); a provider's non-2xx throws `provider_error` with the provider's status and message |
+| `ai.run` | `(tool: string, inputs?: Record<string, string \| number \| boolean>, options?: { stream?: boolean; signal?: AbortSignal })` | `Promise<Response>` — the tool's provider's own answer, untouched (SSE when `stream`). A non-2xx from the provider is returned as-is; a Gemmein refusal throws `GemmeinError` |
+| `ai.runText` | `(tool: string, inputs?: …, options?: { signal?: AbortSignal })` | `Promise<string>` — a non-stream run collected to one string, whichever provider answered; a provider's non-2xx throws `provider_error` |
+| `ai.calls` | `(options?: { limit?: number; before?: string })` | `Promise<{ calls: AiCallRecord[]; nextCursor: string \| null }>` — the signed-in person's own calls, newest first |
+| `ai.chat` | `(body: object, options?: { tool?: string; provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — RAW (needs the owner's switch): the fetch `Response`, untouched |
+| `ai.text` | `(body: object, options?: { tool?: string; provider?: …; signal?: AbortSignal })` | `Promise<string>` — RAW, non-stream, one string |
+
+- **The tool file.** `name` (the file name; fixed once created), `label`,
+  `provider`, `model` (pin it — a composed call needs one; with none, the
+  owner's first allowed model, else the provider's small default),
+  `credits`, `requires`, `enabled`, `bounds`, plus the implementation:
+  `kind` (`chat`, the first), `instructions` (the system turn, ≤ 20,000
+  chars — never leaves the server), `promptTemplate` (the user turn with
+  `{{input}}` placeholders naming declared inputs; ≤ 20,000; absent = the
+  inputs rendered one per line as `name: value`), `inputs` (≤ 20 of
+  `{ name, type: text|number|boolean, required?, maxLength? }` — names
+  1–40 lowercase letters/digits/underscores, starting with a letter; a
+  text input ≤ 4,000 chars
+  unless it says, ≤ 20,000), `recordCalls` (off by default). A tool with
+  neither a template nor inputs composes nothing: `409 tool_incomplete`.
+- **Inputs are checked by name** before any spend: an unknown input, a
+  missing required one, a wrong type or a value over its cap is
+  `400 invalid_inputs` — the message names the input and the rule. The run
+  body is `{ inputs, stream? }` and at most 64 KB.
+- **Composition** per provider: OpenAI `messages` (system + user),
+  `max_completion_tokens`; Anthropic `system` + `messages`, `max_tokens`;
+  Google `systemInstruction` + `contents`, `generationConfig.maxOutputTokens`.
+  The output ceiling is `bounds.maxOutputTokens` or 4,096 — a composed
+  call is never "as long as the model likes". `bounds.stream: false`
+  forces a non-stream answer.
 
 - `tool` names an `ai_tools` row by its slug; omit it for the default tool.
   An unknown name is `404 unknown_tool`; a tool the owner switched off is
@@ -397,7 +587,7 @@ calls the provider directly.
   OpenAI chat completions, Anthropic messages, Google generateContent. Its
   `model` field, when present, must match `^[A-Za-z0-9._:-]{1,80}$`; Google
   needs it (it rides the URL); when the owner lists allowed models (up to
-  20 — the Keys room's test call uses the first), any other answers
+  20 — the AI tools page's test call uses the first), any other answers
   `403 model_not_allowed`.
 - `provider` is optional when one key is configured and required when more
   than one is (`400 provider_required`); a named tool fixes its own
@@ -418,31 +608,45 @@ calls the provider directly.
 - Limits: 20 calls per person per minute (`429 ai_capped`, `resetAt`), 256 KB
   body by default (`413 payload_too_large`, unless a tool sets a smaller
   `bounds.maxBodyBytes`) nested at most 32 levels (`400 invalid_body`),
-  170 s in all and, on a stream, 10 s to the first response headers. Every
+  170 s in all and, on a stream, 10 s to the first response headers. A
+  tool's `credits` are 1–10,000; `bounds.maxOutputTokens` is 1–100,000,
+  4,096 when the tool sets none. Every
   `/ai/chat` call counts toward the app's `api_requests` band like any other
   request.
 
 ```ts
-const res = await g.ai.chat({
-  model: "gpt-4o-mini", stream: true,
-  messages: [{ role: "user", content: text }]
-}, { tool: "deep-research" })
+// gemmein/ai/tools/deep-research.json
+// { "label": "Deep Research", "provider": "openai", "model": "gpt-4o", "credits": 20,
+//   "requires": "access:pro-max",
+//   "instructions": "You are a careful research assistant. Answer with sources.",
+//   "promptTemplate": "Research this for a {{audience}} reader:\n\n{{question}}",
+//   "inputs": [{ "name": "question", "type": "text", "required": true, "maxLength": 2000 },
+//              { "name": "audience", "type": "text" }],
+//   "bounds": { "maxOutputTokens": 4000 } }
+
+const res = await g.ai.run("deep-research", { question: text, audience: "beginner" }, { stream: true })
 for await (const chunk of res.body) render(chunk)      // the provider's SSE, byte for byte
 
-const answer = await g.ai.text({ messages: [{ role: "user", content: text }] }, { tool: "deep-research" })
+const answer = await g.ai.runText("deep-research", { question: text })
+const { calls } = await g.ai.calls()                     // the person's own history
+
+// RAW — only behind the owner's "raw calls" switch for that provider key:
+const raw = await g.ai.chat({ model: "gpt-4o-mini", stream: true, messages: [{ role: "user", content: text }] })
 ```
 
 | code | status | meaning · do |
 |------|--------|--------------|
+| `raw_calls_off` | 403 | The browser may not compose provider requests for this provider — call a named tool with `g.ai.run`, or the owner switches raw calls on for the key on the AI tools page |
+| `invalid_inputs` | 400 | An input is unknown, missing, the wrong type or over its cap — the message names it |
+| `tool_incomplete` | 409 | The tool composes nothing (no template, no inputs) — give it one; the owner's or the file's fix |
 | `unknown_tool` | 404 | No AI tool by this name in this environment — check the slug or the environment |
 | `tool_disabled` | 403 | The owner switched this tool off — turn it on, or use another |
 | `entitlement_required` | 403 | The tool's `requires` names a plan or product this person lacks — the message names it |
 | `model_pinned` | 403 | This tool's model is fixed — leave `model` out of the body |
-| `provider_not_configured` | 409 | Creating or updating a tool: no key is set for that provider yet — add one on the Keys page first |
 | `too_many_tools` | 409 | This environment already holds 50 AI tools — delete one before adding another |
 | `invalid_tool` | 400 | Creating or updating a tool with a bad field — the message names which one and its rule |
 | `credits_exhausted` | 402 | The person's balance is below the tool's price — the message names the tool, the price and the balance ("Deep Research costs 20 credits. You have 7.", singular for 1). Show the pack |
-| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one in the Keys room |
+| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one on the AI tools page. A tool can be defined before its key exists; it runs the moment the key is pasted, and the console shows it as waiting on one until then |
 | `provider_required` | 400 | More than one provider key is set — pass `provider` |
 | `model_not_allowed` | 403 | The owner's allowlist names the models this app may call; the message lists them (only for a tool with no pinned model) |
 | `ai_capped` | 429 | 20 calls per person per minute — wait for `resetAt` |
@@ -451,13 +655,14 @@ const answer = await g.ai.text({ messages: [{ role: "user", content: text }] },
 | `session_required` | 401 | No signed-in person — sign in first |
 | `scope_denied` | 403 | A secret key called the route — the route is for the browser; a server calls the provider directly |
 | `provider_unreachable` | 502 | The provider did not answer before the first byte — nothing was charged (the tool's credits are refunded); retry |
-| `provider_error` | the provider's | `g.ai.text` only (client-side): the provider's own non-2xx, its message in `err.message` |
-| `ai_test_capped` | 429 | The Keys room's test call — one a minute per app |
+| `provider_error` | the provider's | `g.ai.text` and `g.ai.runText` (client-side): the provider's own non-2xx, its message in `err.message` |
+| `invalid_response` | 0 (client-side) | `g.ai.text` and `g.ai.runText`: a non-stream answer with no text to lift out — for a streaming body read the stream with `g.ai.chat` or `g.ai.run` |
+| `ai_test_capped` | 429 | The AI tools page's test call — one a minute per app |
 
 `gemmein dev` answers a fake provider without a key (header `x-gemmein-ai:
 fake`, an echo stream), so the loop runs locally; set
 `GEMMEIN_AI_KEY_OPENAI`, `GEMMEIN_AI_KEY_ANTHROPIC` or `GEMMEIN_AI_KEY_GOOGLE`
-in the local rail's environment for a real call. The owner's Usage room
+in the local rail's environment for a real call. The owner's Usage & billing page
 counts AI calls for the last 30 days: spent by the customers' credits, priced
 by the provider — Gemmein meters the calls, the provider bills the tokens.
 
@@ -477,6 +682,32 @@ signed in, it can create them by email first.
 | `grantAccess` | `(personId, { entitlement, source?, expiresAt?, reason? })` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` (201) — `holdings` is the state **after**; the owner's audit row carries before→after and the key's name |
 | `revokeAccess` | `(personId, grantId, { reason? }?)` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` — the returned grant carries `revokedAt` |
 | `invitePerson` | `(email)` | `Promise<{ person: InvitedPerson, created: boolean }>` — create a person by email **before they sign in** (201 `created: true`), or find them (200 `created: false`); idempotent, case-insensitive, one id. `InvitedPerson = { id, email, role, invited, suspended }` — `invited` stays true until their first sign-in; a suspended person is returned flagged. The one server call that takes an email |
+| `notify` | `(personId, { subject, text, kind?, key? })` | `Promise<{ sent, deduped?, recorded?, id, threadId, replyRail? }>` — email one of your verified people by id; see **Notify** above |
+| `spendCredits` | `(personId, { amount?, reason, key? })` | `Promise<{ ok, spent, deduped, balance: { before, after }, event }>` — one conditional decrement, floored at zero; see **Credits** above |
+| `collection(name).get / .list / .update` | `(as the browser client)` | scoped per collection on the key; no creates, no deletes, no auth access; see **Setup** |
+| `testSession` | `(email)` | `Promise<{ token, expiresAt, user }>` — development only; `sk_live` throws `test_session_forbidden_live`; see **Reaffirm** below |
+
+
+**Swift.** `GemmeinServer` ships in the Swift package for Swift that runs on a
+server. It takes a secret key, and a secret key never belongs in an app bundle
+— `Gemmein` refuses one.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `verifySession(_:)` | `func verifySession(_ token: String) async throws -> PersonHoldings` | `PersonHoldings { person: GatePerson, holdings: Holdings }` — no `ok` field; a refusal throws |
+| `holdings(_:)` | `func holdings(_ personId: String) async throws -> PersonHoldings` | `PersonHoldings` |
+| `grantAccess(_:entitlement:source:expiresAt:reason:)` | `@discardableResult func grantAccess(_ personId: String, entitlement: String, source: ManualGrantSource? = nil, expiresAt: String? = nil, reason: String? = nil) async throws -> GrantResult` | `GrantResult { grant: Grant, holdings: Holdings }` |
+| `revokeAccess(_:_:reason:)` | `@discardableResult func revokeAccess(_ personId: String, grantId: String, reason: String? = nil) async throws -> GrantResult` | `GrantResult` |
+| `invitePerson(_:)` | `func invitePerson(_ email: String) async throws -> InviteResult` | `InviteResult { person: GatePerson, created: Bool }` |
+| `notify(_:subject:text:kind:key:)` | `@discardableResult func notify(_ personId: String, subject: String, text: String, kind: NotifyKind? = nil, key: String? = nil) async throws -> NotifyResult` | `NotifyResult { sent: Bool, deduped: Bool?, id: String?, threadId: String?, replyRail: Bool?, recorded: Bool? }` — `subject` and `text` are required labels, not an options object |
+| `spendCredits(_:amount:reason:key:)` | see **Credits** above | `SpendCreditsResult` |
+| `collection(_:)` | `func collection(_ name: String) throws -> ServerCollectionClient` | `ServerCollectionClient` — `func get(_ id: String) async throws -> GemmeinRecord`, `func list(_ options: ListOptions = ListOptions()) async throws -> ListResult`, `@discardableResult func update(_ id: String, _ data: [String: JSONValue]) async throws -> GemmeinRecord` |
+| `testSession(_:)` | `func testSession(_ email: String) async throws -> AuthSession` | `AuthSession` — development only |
+
+`GatePerson { id: String, email: String, role: String, suspended: Bool?, invited: Bool? }`,
+`Holdings { access: [String], grants: [Grant], credits: Int? }` — a bare `Int?`
+where JS nests `{ balance }`. `ManualGrantSource` is `.manual`, `.trial`,
+`.promotion`, `.migration`; `NotifyKind` is `.event` or `.account`.
 
 ```ts
 type Holdings = {
@@ -530,7 +761,7 @@ type Grant = {
   make two grants — call it once and keep your own retry key.
 - **Nothing silent, within a stated bound.** Every `/server/*` call a **resolved
   secret key** makes, ok or refused, lands in that key's usage ledger — the owner
-  reads the summary on their Keys page and the full day × route × outcome table in
+  reads the summary on their Secret keys page and the full day × route × outcome table in
   the key's own room. A rejected or publishable (`pk_`) key can't be attributed to a
   key row, so its refusal reaches only the request log. Refusals also write one audit
   row per key, route and code each hour (exact counts stay in the ledger); grants and
@@ -569,8 +800,10 @@ provider's webhook arriving, a clock, a record changing — and one to ten of
 Gemmein's **own** verbs, run in order: write a record, grant or revoke access,
 email the person, call your URL. Gemmein runs no code of yours inside one;
 compute lives on your host, behind `call_url`. The definition is a JSON file
-your AI writes; the owner's dashboard shows it read-only with its receiver URL,
-its secrets (shown once), every event with each action's result, and a replay
+your AI writes, or the owner writes in the dashboard, which creates and edits
+it too, pauses, resumes, rotates and deletes it, and shows where it came from
+("from file, synced <when>" / "edited here <when>"), its receiver URL, its
+secrets (shown once), every event with each action's result, and a replay
 button. There is no SDK method: the surface is the file and the dashboard.
 Stripe stays built in; any provider that signs its webhooks — GoCardless, Paddle,
 Lemon Squeezy among them — drives access the same way through a relay, and the
@@ -673,7 +906,7 @@ authorise on fields they cannot set, or from a receiver.
 | `revoke_access` | `entitlement` | ends every live grant of that entitlement the person holds; skipped when none |
 | `fulfil_product` | `product` (name, 1-40 chars), `ref?` (≤ 200, templated) | grants the product's key and credits to the event's person and writes the receipt, exactly as a Stripe purchase does; idempotent on `ref` (an absent `ref` → `rly:<eventId>`; a `ref` you wrote that names nothing on the event is refused, never replaced); a ref must be the provider's unique payment identifier; a ref already used by another purchase is refused and audited; the product's road must be this relay. The relay road binds by name: renaming or deleting the relay stops fulfilment until a relay with that name exists again; the product card shows it. |
 | `refund_product` | `product` (name, 1-40 chars), `ref?` (≤ 200, templated) | takes back what `fulfil_product` under the same `ref` granted; `refund_product` may run from any relay in the environment; it refunds only a purchase a relay fulfilled, for the event's person and the product it names; idempotent on `ref` |
-| `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event |
+| `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event; and rides `notify()`'s sender law — it goes only from your verified sender domain, and until one is verified this action alone is refused `sender_domain_required` and the event's result says so. Nothing is sent via Gemmein |
 | `call_url` | `url` | https only, no template in the URL, no IP literal, never a gemmein.com host, no credentials in the URL; `gemmein dev` allows http to localhost |
 
 **The `call_url` contract.** Gemmein POSTs JSON:
@@ -760,7 +993,16 @@ receiver's local URL), schedules and data changes with the same runner and
 prints `RELAY · <name> · <trigger> · <n actions> · ok|failed`;
 `npx gemmein sync` carries the files to the cloud app's development
 environment with the collections — contract, never data; the cloud mints its
-own secrets.
+own secrets. After go-live, `npx gemmein sync --live` carries relays and AI
+tools into production: it asks for a **sync key** (Secret keys → production →
+Sync key — step-up to mint, lives one hour, shown once, never saved by the
+CLI), prints what would change, waits for the word `live`, never deletes, and
+refuses collections (they move by promotion). A row edited in the dashboard
+since the last sync is asked about, per item (`--overwrite` answers yes);
+every relay says where its definition came from — from file, or edited in the
+dashboard — and when. A relay's name is fixed once created: the receiver URL
+is built from it, so a rename is refused (`invalid_definition`) — create the
+new one, delete the old in the dashboard once the provider has moved.
 
 ---
 
@@ -793,7 +1035,10 @@ line; a wrong-but-well-formed name surfaces as `unknown_collection` and exits
 
 ### `gemmeinServer(sk).testSession(email) → { token, expiresAt, user }`
 **Dev only** — throws `test_session_forbidden_live` on an `sk_live` key, and
-the server refuses it on a live environment too. Pass the `token` to
+the server refuses it on a live environment too. Test **people** only: a
+server key is refused the account owner's or an admin's email
+(`scope_denied`) — the app's CLI key (Setup page) is the credential that
+acts as the founder, and it is the only key that links or syncs. Pass the `token` to
 `gemmein(pk, { tokenStore })` to act as that user. Dev and live enforce the
 *same* rules, so what is proven in dev holds in live.
 
@@ -817,6 +1062,102 @@ current. Add a probe whenever you add a feature.
 
 ---
 
+## Swift — the package
+
+`GemmeinSwift` is the same HTTP contract and the same method names as
+`@gemmein/sdk`, in Swift idiom, for iOS 17+ and macOS 14+, with no
+dependencies:
+
+```swift
+.package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.10.0")
+```
+
+Every method is beside its JavaScript twin in the sections above, under
+**Swift**. Argument labels are as written there; everything that leaves the
+device is `async throws` and throws `GemmeinError`. The parity check
+(`tests/security/sdkParity.test.ts`) holds the two method lists equal and
+`tests/security/docsSwiftReference.test.ts` holds every signature on this page
+to the package's own source, so a signature here is the signature the compiler
+sees.
+
+```swift
+let g = try Gemmein(appKey: "pk_live_…")
+let notes = try g.collection("notes")
+let page = try await notes.list(ListOptions(limit: 20, sort: .newest))
+let note = try await notes.create(["title": .string(typed), "done": false])
+```
+
+### The client
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `Gemmein(appKey:…)` | `init(appKey: String, apiURL: URL = defaultAPIURL, tokenStore: TokenStore? = nil, platform: String? = nil, session: URLSession = .shared) throws` | `Gemmein` — throws `invalid_app_key` on an `sk_`, `missing_app_key` on anything that is not a `pk_` |
+| `g.collection(_:intent:)` | `func collection(_ name: String, intent: String? = nil) throws -> CollectionClient` | `CollectionClient` — `g.storage.collection(_:intent:)` is the same factory, the same signature |
+| `GemmeinServer(secretKey:…)` | `init(secretKey: String, apiURL: URL = defaultAPIURL, session: URLSession = .shared) throws` | `GemmeinServer` — see **Server gate** above |
+
+`apiURL` points at a local `gemmein dev` engine while you build; `tokenStore`
+defaults to `KeychainTokenStore`, so a relaunch keeps the person signed in;
+`platform` defaults to this OS and is appended to `x-client-info`.
+`g.auth`, `g.storage`, `g.subscriptions`, `g.payments`, `g.purchases`,
+`g.account`, `g.files`, `g.credits`, `g.ai` and `g.tokenStore` are `public let`
+properties on `Gemmein`.
+
+### The three shapes that differ from JavaScript
+
+- `credits.balance()` answers a bare **`Int`** — the number itself, not a
+  `{ balance }` wrapper.
+- `files.link(_:)` answers a `FileLink` whose `url` is a **`String`**; pass it
+  through `URL(string:)` before `AsyncImage`.
+- A record body and an AI body are `[String: JSONValue]`. A **literal** needs
+  no ceremony (`["title": "Ran", "done": false, "seats": 4]`); a **variable**
+  needs its case (`["title": .string(typed), "seats": .int(count)]`).
+
+### The session store
+
+`TokenStore` is a protocol — `func get() async -> String?`,
+`func set(_ token: String) async throws`, `func clear() async`.
+`KeychainTokenStore(appKey:)` is the default and `MemoryTokenStore(token:)` is
+there for tests and for the app that catches `secure_store_unavailable`.
+Only `set` throws, on all three of the SDK's stores.
+
+Everything the package throws is a `GemmeinError`
+(`status: Int`, `code: String`, `message: String`, `resetAt: String?`,
+`requires: String?`) — the same table below.
+
+---
+
+## Expo — `@gemmein/sdk/expo`
+
+The same package, a second entry point. `export *` re-exports the whole core
+surface, so an Expo app imports from one place; what follows is everything the
+entry adds. The peers install in the app, not in your monorepo:
+`npx expo install expo-secure-store expo-file-system`.
+
+```ts
+import { createExpoGemmein } from "@gemmein/sdk/expo"
+import { AppState, Platform } from "react-native"
+
+export const g = createExpoGemmein({ appKey: "pk_live_..." }, { AppState, Platform })
+```
+
+| Export | Signature | What it is |
+|---|---|---|
+| `createExpoGemmein` | `(options: GemmeinOptions, modules?: ExpoModules) => Gemmein` | The client. It **is** `Gemmein` — the four seams a phone has, filled in, plus the picker conversion in front of every `upload()`. Anything you pass in `options` wins over the defaults |
+| `SecureStoreTokenStore` | `new SecureStoreTokenStore(appKey: string, secureStore?: SecureStoreModule)` | The `TokenStore` backed by `expo-secure-store` — `get(): Promise<string \| undefined>`, `set(token: string): Promise<void>`, `clear(): Promise<void>`. Keyed `gemmein_session_<first 20 of the app key>`, `WHEN_UNLOCKED_THIS_DEVICE_ONLY`, so the token never rides an iCloud backup. Reads and clears degrade to "signed out"; a refused **write** throws `secure_store_unavailable` |
+| `appStateVisibility` | `(appState?: AppStateModule) => VisibilityHook` | The `visibility` hook `watch()` sleeps on, answered by React Native's `AppState` instead of `document.visibilityState`. Only `"active"` counts as visible; before the module resolves the app is treated as visible |
+| `expoFetch` | `(injected?: typeof fetch) => typeof fetch` | `expo/fetch`, resolved on the first request, `globalThis.fetch` if it is not there. React Native's own fetch is XHR-backed and cannot give a streaming body, which is what `g.ai.chat({ stream: true })` and `g.ai.run(…, { stream: true })` return |
+| `expoPlatformTag` | `(platform?: PlatformModule) => string` | The `platform` string on `x-client-info`: `expo-ios`, `expo-android`, `expo-web`, or `expo` when no `Platform` was passed |
+| `expoUploadPart` | `(file: UploadInput, modules?: ExpoModules) => Promise<UploadInput>` | A picker's `{ uri, name, type, size }` turned into an `expo-file-system` `File`, because Expo's `FormData` refuses a bare picker part. Anything already carrying bytes passes through. Without `expo-file-system` it throws `upload_input_unsupported` |
+| `SECURE_STORE_VALUE_LIMIT` | `2048` | The byte ceiling on a secure-store value. Over it, `set` throws `token_too_large` rather than letting iOS throw a native error the app cannot read |
+| `ExpoModules` | `{ SecureStore?: SecureStoreModule; AppState?: AppStateModule; Platform?: PlatformModule; FileSystem?: FileSystemModule; fetch?: typeof fetch }` | The second argument. Every key optional: pass none and the entry resolves each module lazily on the first call that needs it; pass your own — an app's static imports, a test's fakes — and there is no dynamic resolution at all |
+
+`SecureStoreModule`, `AppStateModule`, `PlatformModule` and `FileSystemModule`
+are the exported types of those four slices — the little of each module this
+entry calls, and nothing more. Nothing is imported from Expo or React Native at
+module load, so the entry resolves in Node too.
+
+---
+
 ## Errors — `GemmeinError`
 
 Every failed call throws a `GemmeinError`:
@@ -844,6 +1185,9 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `entitlement_required` | 403 — signed in, but not on a plan (or holding a product) this collection is unlocked by; `err.requires` is that plan's key (`access:<slug of its name>`) | show your upgrade screen and send them to checkout — the one 403 that succeeds later |
 | `not_found` | record you can't see (existence not leaked) | treat as absent |
 | `denied` | 401 (sign in first) or 429 (rate limit — see `resetAt`) | re-auth or wait+retry |
+| `invalid_body` | 400 — the request body is not a JSON object (an array or a bare value was sent) | send an object |
+| `missing_params` | 400 — a required field is absent or EMPTY; the message names it (`missing email`, `missing code`). The SDK passes what you give it, so a blank form field reaches the API as missing | check the field before calling — a blank email is not a sign-in attempt |
+| `field_too_long` | 400 — a sign-in field (`email`, `code`, the test-session fields) is over 500 characters; the message names the field | shorten it |
 | `conflict` | a keyed create / floor / stale `ifVersion` | it's the mechanism — tell the user it's taken |
 | `html_not_allowed` | HTML in a community/addressed/direct field | store plain text |
 | `invalid_publish` | `{ published }` on a non-public rule | drop it |
@@ -853,36 +1197,43 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `invalid_limit` | `limit` isn't a whole number from 1 to 100 (the message says so: "limit must be between 1 and 100") | ask for at most 100 and page with `cursor` — nothing is clamped for you |
 | `not_a_customer` (404) | `notify()`'s recipient isn't a verified person of this app and environment | fix the person id — one code on purpose |
 | `in_flight` (409) | a `notify()` with the same `key` is sending right now | retry in a moment — a delivered send answers idempotently |
+| `sender_domain_required` (409) | `notify()` (and a relay's `email_person`) with no verified sender domain — your app's mail goes only from your own domain | verify a sender domain on the Domains page, then retry with the same key. Nothing was sent, recorded or capped |
 | `invalid_audience` | `for` isn't a user of this app | fix the recipient id |
 | `unknown_record` | a link field points at a missing record (live only) | fix the id |
-| `payload_too_large` / `file_too_large` | over the size cap (message states it) | shrink it |
+| `payload_too_large` / `file_too_large` | over the size cap (message states it): a record's data over 32 KB, an upload over 25 MB | shrink it — files go through uploads, never inline |
 | `invalid_file_content` | uploaded bytes aren't the claimed type (usually a renamed file) | send the real file |
 | `test_session_forbidden_live` | `testSession()` called on a live env / `sk_live` key | reaffirm's Tier B is dev-only — point it at your dev environment |
 | `unknown_plan` | no plan by that name | use a name from the list in the message |
 | `plan_not_purchasable` | tried to check out the free default plan | nothing to buy — gate on the paid plan's name |
 | `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
-| `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
+| `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes); a server key asked to sign in as the account owner or an admin, or to link/sync; a sync key asked for anything but relays and AI tools | scope the key to that collection, or use the right surface — linking and dev sync use the CLI key (Setup), production sync a Sync key (Secret keys → production) |
+| `secret_key_expired` (403) | a sync key past its hour — the message names the instant | mint a new Sync key (Secret keys → production) and run `npx gemmein sync --live` again |
 | `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
 | `invalid_key` | a keyed create's `key` breaks the charset/length law — or `spendCredits`' `key` is not text of up to 200 chars | 1-120 chars of letters, numbers, `: _ . @ / -` (a create); text ≤ 200 (a spend) |
 | `invalid_amount` / `invalid_reason` (400) | `spendCredits`: `amount` outside 1..10,000, or `reason` missing / over 200 chars | fix the field the code names |
 | `dedupe_conflict` (409) | `spendCredits`: the `key` already names a different movement (another kind or another person) | a key is one movement — reuse it only to retry that same one |
 | `credits_ceiling` (409) | a credit would carry the balance past 1,000,000,000 (a comp, a pack, a relay grant) — nothing was added | the balance is at its most |
 | `invalid_body` (400) | on `g.ai.chat`: the body is not the provider's JSON request object, or is nested deeper than 32 levels | send the provider's own request object |
-| `provider_error` (client-side, the provider's status) | `g.ai.text`: the provider answered a non-2xx; `err.message` is the provider's own reason | read it — the credit was refunded when the provider failed before its first byte |
-| `ai_test_capped` (429) | the Keys room's test call — one a minute per app | wait a minute |
+| `provider_error` (client-side, the provider's status) | `g.ai.text` and `g.ai.runText`: the provider answered a non-2xx; `err.message` is the provider's own reason | read it — the credit was refunded when the provider failed before its first byte |
+| `ai_test_capped` (429) | the AI tools page's test call — one a minute per app | wait a minute |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
-| `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein | check `apiUrl` and anything rewriting responses; the call is safe to retry |
+| `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein; or `g.ai.text` / `g.ai.runText` got a non-stream provider answer with no text to lift out | check `apiUrl` and anything rewriting responses; the call is safe to retry — for AI, read the stream with `g.ai.chat` or `g.ai.run` |
+| `network_unreachable` (client-side, status 0) | the request never reached Gemmein — no connection, an offline device, a host that does not resolve, an `apiUrl` pointing at nothing; the message names the host, and `err.cause` carries the fetch's own error. A cancel (`{ signal }`) is not this: it stays an `AbortError` | check the connection and the `apiUrl`; the call is safe to retry. "The server said no" and "the server was never reached" are different problems — branch on them separately |
+| `upload_input_unsupported` (client-side, status 0) | `@gemmein/sdk/expo`: `upload()` was handed a picker's `{ uri }` and `expo-file-system` is not installed, so there is nothing to read the bytes with | `npx expo install expo-file-system`, or pass a `Blob` / an `expo-file-system` `File` |
+| `token_too_large` (client-side, status 0) | `@gemmein/sdk/expo`: a value over 2,048 bytes was handed to the device secure store, which iOS refuses with a native throw the app cannot read | store the token, not the session payload — a Gemmein session token is two orders of magnitude smaller |
+| `secure_store_unavailable` (client-side, status 0) | the token store could not KEEP the session, so sign-in throws rather than handing back a session the next launch will lose. **All three stores.** `BrowserTokenStore` (`@gemmein/sdk`): the browser refused the `localStorage` write — private mode past its quota, site data blocked, a sandboxed iframe. `SecureStoreTokenStore` (`@gemmein/sdk/expo`): `expo-secure-store` is not installed, or the device refused the write. Swift `KeychainTokenStore`: the Keychain refused, and the OSStatus is in the message; `-34018` is an unsigned build with no keychain access group. The store's own error is on `err.cause` (in Swift, in the message). Reads and clears stay lenient on all three — an unreadable store means signed out, never a crash | install `expo-secure-store`, or sign the app (ad-hoc is enough). The session is real — the server minted it — so an app that would rather run than stop catches this one code and rebuilds its client with a `MemoryTokenStore`: signed in until the process ends |
+| `invalid_collection_name` (client-side, status 0) | `g.collection(name)` was given a name outside the grammar: lowercase letters, digits and underscores, starting with a letter, 2-63 characters (`tasks`, `user_notes`). Thrown synchronously, before any request exists — the message echoes what it got | fix the name. A collection that exists but is not reachable is a different code (`unknown_collection`, 404) |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
 | `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
 | `product_not_sellable` (409) | `g.payments.buy` on a product sold via a relay or not yet — there is no Payment Link to open | tell the buyer how the product is sold, or ask the owner to wire a road |
 | `relay_missing` (400) | saving a relay action (or a product's `sold.relay`) names a relay that does not exist in this environment | create that relay first, or name one that exists |
 | `account_suspended` (403) | the app owner's account is suspended (billing) | the owner fixes payment at app.gemmein.com |
 | `credits_exhausted` (402) | the person's balance is below the spend — the message carries the balance ("this person has {balance} credits — the spend needs {amount}") | show the pack; never retry the same spend |
-| `ai_not_configured` (409) | no provider key on this app and environment | the owner pastes one in the Keys room |
+| `ai_not_configured` (409) | no provider key on this app and environment | the owner pastes one on the AI tools page |
 | `provider_required` (400) | more than one provider key is set and the call named none | pass `provider` |
 | `model_not_allowed` (403) | the owner's allowlist does not name this model | use one the message lists |
 | `ai_capped` (429) | 20 AI calls per person per minute | wait for `resetAt` |
-| `payload_too_large` (413) | on `g.ai.chat`: the body is over 256 KB | shorten the conversation you send |
+| `payload_too_large` (413) | on `g.ai.chat`: the body is over 256 KB; on `g.ai.run`: the inputs are over 64 KB; on a record write: the data is over 32 KB | shorten the conversation you send; send less; move files to uploads |
 | `session_required` (401) | `g.ai.chat` / `g.credits.balance` without a signed-in person | sign in first |
 | `scope_denied` (403) | on `g.ai.chat`: a secret key called the route | the route is for the browser — a server calls the provider directly |
 | `provider_unreachable` (502) | the provider did not answer before the first byte; the credit is refunded | retry |