@gemmein/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -12,6 +12,79 @@ the same release.
 
 ## [Unreleased]
 
+## [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)
+
+A product is sold one of three ways, set on the Payments page ("How it's
+sold" in the console, `sold` in the CLI): via a Stripe Payment Link, via a
+relay (any provider whose webhook the founder maps — GoCardless, Lemon
+Squeezy, Paddle, bank transfer), or not yet (defined, its grants and
+credits known, no road wired). Two new relay actions carry the relay
+road: `fulfil_product { product, ref? }` grants the product's key and
+credits to the event's person and writes the receipt, exactly as a
+Stripe purchase does; `refund_product { product, ref? }` takes them
+back. Both are idempotent on `ref`. `g.payments.buy` on a product sold
+via a relay or not yet answers 409 `product_not_sellable`; saving a
+relay action or a product's relay road against a relay that does not
+exist in this environment answers 400 `relay_missing`.
+
+### The AI tool primitive (engine 0.9.0, sdk 0.8.0, mcp 0.5.0)
+
+The AI route now runs named, priced tools instead of one flat rate. An
+owner creates an `ai_tools` row (console Tools table, or `PUT
+/internal/ai/tools`; the CLI's `gemmein ai tools` lists, sets and removes
+them, and the local rail reads `gemmein/ai/tools/<name>.json`) — a slug,
+a label, a provider, an optional pinned model, a credit price (1 to
+10,000), an optional `requires` entitlement key, and optional bounds
+(`maxBodyBytes`, `maxOutputTokens`, `stream`). `g.ai.chat` and `g.ai.text`
+take a new `tool` option naming one; a call with no `tool` runs as the
+**default tool** — one credit, the app's configured provider, any allowed
+model — so every existing integration keeps working unchanged. Up to 50
+tools per environment.
+
+New codes: `unknown_tool` (404 — no tool by that name), `tool_disabled`
+(403 — the owner switched it off), `entitlement_required` (403 — the
+message names the plan or product the tool requires), `model_pinned`
+(403 — the tool's model is fixed; leave `model` out of the body),
+`provider_not_configured` (409 — creating a tool on a provider with no
+key set), `too_many_tools` (409 — 50 tools per environment) and
+`invalid_tool` (400 — a bad field creating or updating a tool).
+
+A response from a named tool now carries `x-gemmein-tool` — the tool's slug —
+alongside `x-gemmein-credits-remaining`. `x-gemmein-tool` names the tool;
+absent on the implicit default.
+
 ## [0.7.0] — 2026-09-04
 
 ### Credits and the AI route

package/README.md

@@ -292,7 +292,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.
 

package/REFERENCE.md

@@ -238,6 +238,16 @@ Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 don't also redirect to the returned `url`, and never build a Stripe URL
 yourself. Gate features on `(await g.subscriptions.mine())?.plan === "pro"`;
 gate one-off fulfilment on the receipt record, never the redirect.
+
+A product is sold one of three ways, set on the Payments page: **via a
+Stripe Payment Link** (`buy` navigates there); **via a relay** — any
+provider whose webhook the founder maps (GoCardless, Lemon Squeezy,
+Paddle, bank transfer) fulfils it with the `fulfil_product` relay
+action, and refunds it with `refund_product`; or **not yet** — the
+product is defined, its grants and credits are known, no road wired.
+`buy` on a product sold via a relay or not yet answers 409
+`product_not_sellable`. The price always comes from the provider — the
+Payment Link or the relay — never the app.
 By-hand grants (trial, promotion, a support comp) are not listed to the
 app — a gated read simply succeeds — so never rebuild the paywall from
 `mine()`; let the server refuse with `entitlement_required`. The two grant
@@ -274,7 +284,7 @@ honestly, not hidden.)
 ## Credits — `g.credits` / `gemmeinServer(sk).spendCredits`
 
 A balance your customers hold and your product spends: a pack they buy, a
-comp the owner gives, a call that costs one. Credits are a **quantity beside
+comp the owner gives, an AI tool call priced in credits. Credits are a **quantity beside
 access**, never access itself — a locked collection still asks for the
 entitlement, whatever the balance. The ledger adds at every purchase, grant
 and refund, subtracts at every spend, and never goes below zero: a spend
@@ -302,8 +312,9 @@ Where credits come from, and where they go:
   ledger lines and the credits the person spent in the last 30 days.
 - **A relay** adds with `grant_credits { amount (1..10,000), reason? }` — see
   **Relays**.
-- **Your server** spends with `spendCredits`; **the AI route** spends one per
-  call (see **AI**). Nothing spends from the browser.
+- **Your server** spends with `spendCredits`; **the AI route** spends the
+  credits the owner set for the named tool, one by default (see **AI**).
+  Nothing spends from the browser.
 - Spend lines are kept 90 days on the cloud rail; purchases, grants and
   clawbacks are kept. A balance carries at most 1,000,000,000. Account
   erasure removes the person's balance and ledger.
@@ -342,73 +353,171 @@ 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. The owner
-pastes the key once in the dashboard's Keys room; it is write-only from then
-on. A signed-in person's request costs **one credit**, spent before the
-request is forwarded; the provider bills the tokens on the owner's own
-account. 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.
+**owner's own provider key**, which never reaches the browser, through a
+**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.
+
+**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?: { 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?)` | `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
+  `403 tool_disabled`; a tool gated with `requires` refuses a person who
+  lacks that entitlement with `403 entitlement_required` (the message names
+  the plan or product). A tool with a pinned `model` refuses a body that
+  sets one with `403 model_pinned`; a tool with no pinned model follows the
+  allowlist rule below. A tool's own `bounds.maxBodyBytes` (≤ 262,144)
+  replaces the default 256 KB cap. `bounds.maxOutputTokens` is a ceiling: a
+  larger or absent value in the body becomes the bound; a smaller one stays.
+  It reaches the provider as ONE field, never two: the ceiling is written
+  onto the field the body already used, and a second spelling of the same
+  ceiling is folded away, so a browser cannot buy more output by naming the
+  field the route was not watching. A body that names none is sent the
+  current field — `max_completion_tokens` on OpenAI, `max_tokens` on
+  Anthropic, `generationConfig.maxOutputTokens` on Google.
 - `body` is exactly what the provider documents for its chat endpoint —
   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`). No key at all is
-  `409 ai_not_configured`. `?provider=` and `?stream=1` on the URL do what
-  the body fields do.
-- Two response headers from Gemmein on every answer that passed the spend:
-  `x-gemmein-credits-remaining` (the balance after this call) and, on a
-  refund, `x-gemmein-credit: refunded`.
-- **The refund rule.** A credit is refunded only when the provider fails
-  before its first byte (a non-2xx, or `502 provider_unreachable`). A stream
-  that dies after the first byte is not refunded; hanging up early does not
-  refund. A provider that echoes the key in a refusal reaches the app as
-  `***<hint>`.
+  than one is (`400 provider_required`); a named tool fixes its own
+  provider, and a `provider` in the body or `?provider=` that disagrees with
+  it is `400 invalid_body`. No key at all is `409 ai_not_configured`.
+  `?provider=` and `?stream=1` on the URL do what the body fields do.
+- Response headers from Gemmein. `x-gemmein-credits-remaining` (the balance
+  after this call) rides every answer that passed the spend.
+  `x-gemmein-credit` reads `refunded`, and is there only when the credits
+  came back. `x-gemmein-ai` reads `fake`, and is there only on the local
+  engine's rehearsal answer. `x-gemmein-tool` names the tool; absent on the
+  implicit default.
+- **The refund rule.** The tool's credits are refunded only when the
+  provider fails before its first byte (a non-2xx, or
+  `502 provider_unreachable`). A stream that dies after the first byte is
+  not refunded; hanging up early does not refund. A provider that echoes
+  the key in a refusal reaches the app as `***<hint>`.
 - Limits: 20 calls per person per minute (`429 ai_capped`, `resetAt`), 256 KB
-  body (`413 payload_too_large`) nested at most 32 levels (`400 invalid_body`),
-  170 s in all and, on a stream, 10 s to the first response headers. Every
+  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. 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 }]
-}, { provider: "openai" })
+// 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({ model: "gpt-4o-mini", messages: [{ role: "user", content: text }] })
+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 |
 |------|--------|--------------|
-| `credits_exhausted` | 402 | The person's balance is 0 — the message carries it. Show the pack |
-| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one in the Keys room |
+| `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 AI tools 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 on the AI tools page |
 | `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 |
+| `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` |
-| `payload_too_large` | 413 | The body is over 256 KB — shorten the conversation you send |
-| `invalid_body` | 400 | The body must be the provider's JSON request object, nested at most 32 levels |
+| `payload_too_large` | 413 | The body is over the cap (256 KB, or the tool's own `bounds.maxBodyBytes`) — shorten the conversation you send |
+| `invalid_body` | 400 | The body must be the provider's JSON request object, nested at most 32 levels; or a named tool's own provider was contradicted |
 | `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 credit is 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_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` 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
@@ -525,8 +634,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
@@ -627,6 +738,8 @@ authorise on fields they cannot set, or from a receiver.
 | `grant_access` | `entitlement` (plan or product **name**, or `access:<slug>`), `expiresAt?` (`"30d"`, `"12h"`, `"2w"` or an ISO date), `reason?` (≤ 200, templated) | source `relay`, the seventh grant source; skipped when this event already granted |
 | `grant_credits` | `amount` (1..10,000), `reason?` (≤ 200, templated) | adds to the person's credit balance, once per event (a replay finds its own row); the ledger line reads "relay: <reason>"; a relay adds and never spends |
 | `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 |
 | `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 |
 
@@ -665,11 +778,16 @@ Egress refusals arrive as the action's error, naming the rule: `https_only`,
 ### Templates
 
 In string values only — `write_record.data`, `email_person.subject` / `text`,
-`grant_access.reason`; never in `call_url.url` or an `entitlement`:
+`grant_access.reason`, `fulfil_product.ref` / `refund_product.ref`; never in
+`call_url.url` or an `entitlement`:
 `{{event.a.b}}` (the raw body), `{{mapped.x}}`, `{{record.data.x}}`,
 `{{record.id}}`, `{{person.email}}`, `{{person.id}}`, `{{tick.periodStart}}`.
+Mapped fields ride into templates as `{{mapped.<name>}}`; `{{event.<path>}}`
+reads the raw payload.
 A path that names nothing renders empty and adds a warning to the event;
-objects render as JSON. No expressions, no filters.
+objects render as JSON. No expressions, no filters. The one place an empty
+render is a refusal rather than a blank is a `ref` you wrote on
+`fulfil_product` / `refund_product`.
 
 ### Lifecycle
 
@@ -709,7 +827,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.
 
 ---
 
@@ -742,7 +869,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.
 
@@ -793,6 +923,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 |
@@ -810,22 +943,25 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `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` |
 | `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` |