bkper 5.8.0 → 5.8.2

package/lib/docs/api/ai-gateway.md

@@ -2,7 +2,7 @@
 
 > Call Bkper AI models from your own client or code — the guide, with a page for each operation: models, responses, streaming, and decisions.
 
-The Bkper AI Gateway serves the models behind Bkper's agents and apps to your own clients and code: typed answers from decision models and the stateless Bkper [Open Responses 2026-04-24](https://www.openresponses.org/specification/2026-04-24) profile for language models.
+The Bkper AI Gateway serves the models behind Bkper's agents and apps to your own clients and code: typed answers from System One models and the stateless Bkper [Open Responses 2026-04-24](https://www.openresponses.org/specification/2026-04-24) profile for language models.
 
 [Models and Usage](https://bkper.com/docs/ai/models) covers the models, usage rates, the monthly allowance, and privacy. To run an agent that works on Books instead of calling a model, use the [Managed Agent API](https://bkper.com/docs/api/managed-agent). Building a Bkper app? Start with [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai). The canonical machine-readable contract is [https://ai.bkper.app/openapi.json](https://ai.bkper.app/openapi.json).
 
@@ -10,9 +10,9 @@ The Bkper AI Gateway serves the models behind Bkper's agents and apps to your ow
 
 1. Call `GET /v1/models` to discover the current public model IDs, types, capabilities, limits, and usage rates.
 2. Select a returned model ID.
-3. Call `POST /v1/responses` for language models or `POST /v1/decisions` for decision models.
+3. Call `POST /v1/responses` for language models or `POST /v1/systemone` for System One models.
 
-Responses support complete JSON with `stream: false` or semantic server-sent events with `stream: true`. Decision models return complete JSON and do not stream.
+Responses support complete JSON with `stream: false` or semantic server-sent events with `stream: true`. System One models return complete JSON and do not stream.
 
 ## Requirements
 
@@ -20,7 +20,7 @@ You need:
 
 - a Bkper account with an eligible subscription or trial allowance;
 - a valid Bkper OAuth access token;
-- an Open Responses client with a custom base URL for language generation, or an HTTP client or TypeSafe SDK for decision models.
+- an Open Responses client with a custom base URL for language generation, or an HTTP client or TypeSafe SDK for System One models.
 
 Requests are attributed to the authenticated Bkper user. Business subscriptions use a shared domain allowance. See [Models and Usage](https://bkper.com/docs/ai/models#monthly-allowance) for allowance scope, current rates, and model capabilities.
 
@@ -32,7 +32,7 @@ Requests are attributed to the authenticated Bkper user. Business subscriptions
 | Authentication         | `Authorization: Bearer <Bkper access token>` |
 | Model discovery        | `GET /v1/models`                             |
 | Language generation    | `POST /v1/responses`                         |
-| Decision models        | `POST /v1/decisions`                         |
+| System One models      | `POST /v1/systemone`                         |
 | Open Responses profile | `2026-04-24` for language generation only    |
 
 The live `GET /v1/models` response is authoritative for available IDs, model types, capabilities, limits, and effective usage rates. The catalog publishes `default_model` as the default language model. Inspect each entry's `type` before choosing its endpoint.
@@ -45,7 +45,7 @@ Bkper AI implements a documented subset of Open Responses. It does not claim ful
 
 Use the model IDs returned by `GET /v1/models`, such as `gpt-luna`, `grok`, `gemini-flash`, and `jev`.
 
-Language model entries have `type: "language"` and use `POST /v1/responses`. Decision model entries have `type: "decision"` and use `POST /v1/decisions`. Sending a model to the wrong endpoint fails explicitly.
+Language model entries have `type: "language"` and use `POST /v1/responses`. System One model entries have `type: "system-one"`, list the question types they answer in `question_types`, and use `POST /v1/systemone`. Entries with `preview: true` are provider previews whose answers, limits, and availability may change without notice. Sending a model to the wrong endpoint fails explicitly.
 
 Model IDs remain stable as Bkper updates the model behind them. Older versioned and publisher-prefixed IDs still work, but they select the current model, not the older version. Catalogs, responses, and usage reports use the current ID.
 
@@ -62,7 +62,7 @@ Treat the token as a secret. Do not commit it, print it in shared logs, or put i
 
 ## Call from a browser
 
-Web pages on any origin can call `POST /v1/responses`, `POST /v1/decisions`, and `GET /v1/models` directly. Bkper AI authenticates only the bearer token and uses no cookies, so browser requests carry no credentials.
+Web pages on any origin can call `POST /v1/responses`, `POST /v1/systemone`, and `GET /v1/models` directly. Bkper AI authenticates only the bearer token and uses no cookies, so browser requests carry no credentials.
 
 - **Use the signed-in user's token at runtime.** On `*.bkper.app` pages, `@bkper/web-auth` supplies it. On other domains, use your own Bkper OAuth flow. Never ship a fixed token in a page.
 - **Usage counts against the signed-in user's allowance.** Label it with a `bkper-ai-source` header, such as `my-page`.
@@ -75,7 +75,7 @@ import { BkperAuth } from '@bkper/web-auth';
 const auth = new BkperAuth();
 await auth.init();
 
-const response = await auth.authenticatedFetch('https://ai.bkper.app/v1/decisions', {
+const response = await auth.authenticatedFetch('https://ai.bkper.app/v1/systemone', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'bkper-ai-source': 'my-page' },
     body: JSON.stringify({
@@ -108,14 +108,14 @@ The response is an Open Responses resource. Its `model` contains the canonical p
 
 The `bkper-ai-source` header is optional. Set it to a stable lowercase identifier such as `my-harness` to see which client or application made a request in the usage dashboard. Without a valid identifier, the source appears as unknown.
 
-## Decision models
+## Decision questions
 
-`POST /v1/decisions` answers typed questions about a shared state instead of generating text. Each question returns a noul probability, one choice from options you define, or a level on an ordered score, and your code decides what to do with it. Designing the questions, thresholds, and human review is covered in the [Decision Models guide](https://bkper.com/docs/ai/decision-models).
+`POST /v1/systemone` answers typed questions about a shared state instead of generating text. Each question returns a noul probability, one choice from options you define, or a level on an ordered score, and your code decides what to do with it. Designing the questions, thresholds, and human review is covered in the [System One Models guide](https://bkper.com/docs/ai/system-one-models). `POST /v1/decisions` is a deprecated alias with identical behavior.
 
-For an incoming bank line, this request asks three questions at once: which Account it belongs to, whether it is already recorded, and how urgently it needs review.
+For an incoming bank line, this request asks for three judgments at once: which Account it belongs to, whether it is already recorded, and how unusual it is as a business expense. Code combines the answers with facts, such as the amount, into what to do with the line.
 
 ```bash
-curl --fail-with-body https://ai.bkper.app/v1/decisions \
+curl --fail-with-body https://ai.bkper.app/v1/systemone \
   -H "Authorization: Bearer ${BKPER_TOKEN}" \
   -H "Content-Type: application/json" \
   -H "bkper-ai-source: my-app" \
@@ -152,13 +152,13 @@ curl --fail-with-body https://ai.bkper.app/v1/decisions \
         "type": "noul",
         "instructions": "Does `existing_transaction` already record the movement in `bank_line`?"
       },
-      "review_priority": {
+      "unusual": {
         "type": "score",
-        "instructions": "How urgently should a bookkeeper review `bank_line`?",
+        "instructions": "How unusual is `bank_line` as a business expense?",
         "criteria": [
-          "Routine: consistent with normal activity",
-          "Check: unusual but plausibly legitimate",
-          "Urgent: large, unapproved, or suspicious"
+          "Routine: a common business expense",
+          "Unusual: plausible, but uncommon for a business",
+          "Suspicious: looks like fraud, an error, or a personal expense"
         ]
       }
     }
@@ -167,14 +167,15 @@ curl --fail-with-body https://ai.bkper.app/v1/decisions \
 
 ### Decision request
 
-- **`model`** is any model with `type: "decision"` in `GET /v1/models`, such as `jev`. Each entry lists its `question_types`, `context_window`, and `max_state_question_tokens`.
-- **`state`** is what every question judges: a string, JSON object, or array. Prefer an object with descriptive field names. Decision models read text only, so convert images and files to text first.
+- **`model`** is any model with `type: "system-one"` in `GET /v1/models`, such as `jev` or `clef`. Each entry lists its `question_types`, `context_window`, and `max_state_question_tokens`; a question whose type is not in the model's `question_types` returns `unsupported_question_type`.
+- **`state`** is what every question judges: a string, JSON object, or array. Prefer an object with descriptive field names. Convert PDFs and other files to text first, or to image `assets` for models with image input.
 - **`questions`** is a nonempty map. Question IDs such as `account` are yours, and answers come back under the same IDs, but **IDs are not sent to the model**, so each `instructions` must stand on its own. Refer to state fields by name in backticks, as in `` `bank_line` ``.
 - Each question accepts only `type`, `instructions`, and `criteria`. Instructions, descriptions, and levels can be strings or [structured JSON](https://docs.typesafe.ai/primitives/advanced):
   - **`noul`**: optional `criteria` describe what yes and no mean.
   - **`choice`**: `criteria` maps 1–255 options to descriptions, which may be `null`.
   - **`score`**: `criteria` lists 2–10 levels, lowest first.
-- The body accepts only `model`, `state`, and `questions`. Responses fields such as `input`, `stream`, `store`, `temperature`, and `metadata` are rejected.
+- The body accepts only `model`, `state`, and `questions`, plus image `assets` on models with image input. `reference_date` applies only to extraction questions; `jev` and `clef` reject it with `unsupported_parameter`. Responses fields such as `input`, `stream`, `store`, `temperature`, and `metadata` are rejected.
+- **`clef`** answers at most 64 questions, named with up to 100 letters, digits, `_`, `.`, or `-`, and needs at least 2 choice options. It reads up to 4 image `assets` (4 MiB each, 8 MiB in total) before the state, in `assets` order. Requests beyond these limits return `unsupported_parameter`; input over its 65,536-token context returns `provider_rejected`.
 
 The model evaluates each question independently and in parallel against the same state.
 
@@ -191,33 +192,33 @@ A real response to the request above:
             "choice": "Office Supplies",
             "confidence": 1,
             "probabilities": {
-                "Office Supplies": 1,
                 "Cloud Hosting": 0,
-                "Travel": 0,
-                "Software Subscriptions": 0
+                "Software Subscriptions": 0,
+                "Office Supplies": 1,
+                "Travel": 0
             }
         },
         "already_recorded": {
             "type": "noul",
-            "noul": 0.89
+            "noul": 0.91
         },
-        "review_priority": {
+        "unusual": {
             "type": "score",
-            "score": 0.09,
-            "confidence": 0.86,
+            "score": 0.17,
+            "confidence": 0.74,
             "legend": {
-                "0": "Routine: consistent with normal activity",
-                "1": "Check: unusual but plausibly legitimate",
-                "2": "Urgent: large, unapproved, or suspicious"
+                "0": "Routine: a common business expense",
+                "1": "Unusual: plausible, but uncommon for a business",
+                "2": "Suspicious: looks like fraud, an error, or a personal expense"
             },
             "probabilities": {
-                "0": 0.91,
-                "1": 0.09,
-                "2": 0
+                "0": 0.9,
+                "1": 0.03,
+                "2": 0.07
             }
         }
     },
-    "usage": { "input_tokens": 607, "output_tokens": 86 }
+    "usage": { "input_tokens": 614, "output_tokens": 87 }
 }
 ```
 
@@ -248,23 +249,96 @@ Decision errors use the shared [error envelope](#errors). Validation failures na
 }
 ```
 
-Besides `invalid_request`, decision validation returns `400` with `missing_model`, `unsupported_model`, `invalid_state`, `invalid_questions`, `invalid_question`, or `unsupported_question_type`. Fix the field named in `error.param`; do not retry unchanged. A `400` with `provider_rejected` means the model rejected the request: check its size against the model's limits.
-
-### Decision caching
-
-Bkper caches decision results for 15 minutes per user. An identical request in that window returns the same answers without calling the model or consuming allowance, and repeats the original `usage`. Aliases of the same model share one cache entry. To get fresh answers, change the request or wait. See [Privacy, retention, and caching](https://bkper.com/docs/ai/models#privacy-retention-and-caching).
+Besides `invalid_request`, decision validation returns `400` with `missing_model`, `unsupported_model`, `invalid_state`, `invalid_questions`, `invalid_question`, `unsupported_question_type`, or `unsupported_parameter`. The last two follow [Open System One](https://github.com/bkper/open-systemone/blob/9c454705012d1b659320340e4846a5824bd8e4fc/SPEC.md#errors): `unsupported_question_type` for a question type the selected model does not answer, and `unsupported_parameter` for a field the specification defines that the model cannot honor, such as `reference_date`. Fix the field named in `error.param`; do not retry unchanged. A `400` with `provider_rejected` means the model rejected the request: check its size against the model's limits. A `502` with `provider_invalid_answer` means the model's answers broke an [Open System One answer guarantee](https://github.com/bkper/open-systemone/blob/9c454705012d1b659320340e4846a5824bd8e4fc/SPEC.md#answer-guarantees); `error.message` names the question and the rule, and no answers are returned.
 
 ### TypeSafe compatibility
 
-Decision models come from TypeSafe's [System One](https://docs.typesafe.ai/concepts/system-one), and request and answer shapes match TypeSafe's [`POST /v1/systemone`](https://docs.typesafe.ai/api). TypeSafe's guidance on questions, state, confidence, and patterns applies unchanged. Only the surroundings differ:
+Decision questions come from TypeSafe's [System One](https://docs.typesafe.ai/concepts/system-one), and request and answer shapes match TypeSafe's [`POST /v1/systemone`](https://docs.typesafe.ai/api). TypeSafe's guidance on questions, state, confidence, and patterns applies unchanged. Only the surroundings differ:
 
-- **Endpoint and authentication.** Call `https://ai.bkper.app/v1/decisions` with a Bkper access token. TypeSafe API keys do not work here.
-- **SDKs.** TypeSafe SDKs work with base URL `https://ai.bkper.app`, without `/v1`, and a Bkper access token. See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai#ask-a-decision-model).
+- **Endpoint and authentication.** Call `https://ai.bkper.app/v1/systemone` with a Bkper access token. TypeSafe API keys do not work here.
+- **SDKs.** TypeSafe SDKs work with base URL `https://ai.bkper.app`, without `/v1`, and a Bkper access token. See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai#ask-a-system-one-model).
 - **Errors.** Bkper returns `400` where TypeSafe returns `422`, and `503` with `provider_overloaded` where TypeSafe returns `529`. A `429` can also mean the Bkper AI allowance is exhausted.
 - **Usage.** Requests count against the Bkper AI allowance, not a TypeSafe account.
-- **Images.** Send images as base64 `assets` in a JSON request, as in TypeSafe's [Images](https://docs.typesafe.ai/images) guide. TypeSafe SDKs upload images as multipart, which Bkper does not accept, so send image requests over HTTP. Bkper turns on TypeSafe's experimental image input for you. Box questions are not supported. Image tokens count as input tokens.
+- **Images.** Send images as base64 `assets` in a JSON request, as in TypeSafe's [Images](https://docs.typesafe.ai/images) guide. TypeSafe SDKs upload images as multipart, which Bkper does not accept, so send image requests over HTTP. Bkper turns on TypeSafe's experimental image input for you. Jev reads `png`, `jpg`, and `jpeg` images; `webp`, which `clef` and `clairic` read, returns `unsupported_parameter`. Box questions are not supported. Image tokens count as input tokens.
 - **Coding agents.** TypeSafe's [agent skill](https://docs.typesafe.ai/agent-skill) teaches questions and patterns. For a Bkper integration, also point the agent to this guide, `https://bkper.com/docs/api/ai-gateway.md`, for the endpoint, authentication, model IDs, and errors.
 
+## Extraction questions
+
+Extraction questions to `POST /v1/systemone` ask for values read, computed, estimated, or forecast from the state instead of judgments: `text`, `number`, `date`, `time`, `datetime`, `duration`, `list`, `estimate`, and `forecast`. `clairic` is a Cloudflare preview (`preview: true` in `GET /v1/models`). Question and answer shapes follow [Open System One](https://github.com/bkper/open-systemone/blob/9c454705012d1b659320340e4846a5824bd8e4fc/SPEC.md#question-types).
+
+This request reads a supplier email: it copies the invoice number, reads the issue date and payment terms, and estimates when the invoice will be paid. An extraction question can also ask for a computed value, such as a due date, but when a value feeds a Book, ask for its inputs and compute it in code.
+
+```bash
+curl --fail-with-body https://ai.bkper.app/v1/systemone \
+  -H "Authorization: Bearer ${BKPER_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "bkper-ai-source: my-app" \
+  --data '{
+    "model": "clairic",
+    "state": "Hi, this is Marta Silva from Acme Paper. Invoice AP-5531 for 3 boxes of A4 paper is attached: total $184.50, issued 2026-03-02 with net 30 terms. Delivery is booked for March 9 at 10:15 am, and unloading takes about 40 minutes. Our last four monthly invoices were $172.00, $178.25, $181.10 and $184.50.",
+    "reference_date": "2026-03-05",
+    "questions": {
+      "invoice_number": {"type": "text", "instructions": "Invoice number"},
+      "contacts": {"type": "list", "items": "text", "instructions": "Each person named"},
+      "total": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Invoice total"},
+      "issue_date": {"type": "date", "instructions": "Invoice issue date"},
+      "net_days": {"type": "number", "integer": true, "unit": "days", "instructions": "Net payment terms"},
+      "delivery_time": {"type": "time", "instructions": "Time the delivery is booked for"},
+      "delivery_at": {"type": "datetime", "instructions": "Date and time of the delivery"},
+      "unloading": {"type": "duration", "unit": "minutes", "integer": true, "instructions": "How long unloading takes"},
+      "monthly_amounts": {"type": "list", "items": "number", "decimals": 2, "instructions": "Each monthly invoice amount"},
+      "days_to_pay": {"type": "estimate", "min": 0, "max": 90, "step": 1, "instructions": "Days after issue until this invoice is paid"},
+      "next_invoices": {"type": "forecast", "min": 0, "max": 1000, "horizon": 2, "interval": "month", "unit": "USD", "instructions": "Amount of the next monthly invoices", "step": 0.01},
+      "po_number": {"type": "text", "instructions": "Purchase order number"}
+    }
+  }'
+```
+
+### Extraction request
+
+- **Settings** are optional except `items` on lists and `min` and `max` (and `horizon` on forecasts) on estimates and forecasts: `null_threshold` on value types; `unit`, `integer`, and `decimals` on numbers and durations; `step` and `scale` on estimates and forecasts; `quantiles: true` on estimates for the 1st to 99th percentiles; `interval` on forecasts. An invalid setting returns `400` with `invalid_question` and the setting in `error.param`.
+- **`instructions`** is optional. Structured state and instructions are read as compact JSON text.
+- **`reference_date`** (`YYYY-MM-DD`) resolves relative and year-less dates, such as "March 9" above.
+- **`clairic`** accepts question names of up to 64 letters, digits, `_`, `.`, or `-`, starting with a letter or `_`, forecasts of up to 64 steps, and up to 4 image `assets` (4 MiB each, 8 MiB in total). Requests beyond these limits return `unsupported_parameter`.
+
+### Extraction answers
+
+A real response to the request above, with probabilities and means rounded:
+
+```json
+{
+    "model": "clairic",
+    "answers": {
+        "invoice_number": {"type": "text", "value": "AP-5531", "guess": "AP-5531", "span": [49, 56], "p_null": 0, "confidence": 1},
+        "contacts": {"type": "list", "value": ["Marta Silva"], "spans": [[12, 23]], "confidence": 0.28},
+        "total": {"type": "number", "value": 184.5, "guess": 184.5, "p_null": 0, "confidence": 1},
+        "issue_date": {"type": "date", "value": "2026-03-02", "guess": "2026-03-02", "p_null": 0, "confidence": 1},
+        "net_days": {"type": "number", "value": 30, "guess": 30, "p_null": 0, "confidence": 1},
+        "delivery_time": {"type": "time", "value": "10:15:00", "guess": "10:15:00", "p_null": 0, "confidence": 1},
+        "delivery_at": {"type": "datetime", "value": "2026-03-09T10:15:00", "guess": "2026-03-09T10:15:00", "p_null": 0, "confidence": 1},
+        "unloading": {"type": "duration", "value": 40, "guess": 40, "p_null": 0, "confidence": 1, "unit": "minutes"},
+        "monthly_amounts": {"type": "list", "value": [172, 178.25, 181.1, 184.5], "confidence": 0.74},
+        "days_to_pay": {"type": "estimate", "value": 30, "median": 30, "p10": 24, "p90": 35, "mean": 29.78, "p_below": 0, "p_above": 0},
+        "next_invoices": {"type": "forecast", "steps": [{"value": 182.95, "median": 183.47, "p10": 171.24, "p90": 195.86, "mean": 182.95, "p_below": 0, "p_above": 0}, {"value": 183.74, "median": 184.1, "p10": 171.64, "p90": 196.86, "mean": 183.74, "p_below": 0, "p_above": 0}]},
+        "po_number": {"type": "text", "value": null, "guess": "AP-5531", "span": [49, 56], "p_null": 1, "confidence": 0.99}
+    },
+    "truncated": false,
+    "usage": { "input_tokens": 1337, "output_tokens": 0 }
+}
+```
+
+Bkper checks every answer against the [Open System One answer guarantees](https://github.com/bkper/open-systemone/blob/9c454705012d1b659320340e4846a5824bd8e4fc/SPEC.md#answer-guarantees) before returning it:
+
+- Value types have `value`, `p_null`, and `confidence`. `value` is `null` exactly when `p_null` is above the question's `null_threshold` (default 0.5), as for `po_number`; `guess` is still the most likely value.
+- `span` is where `guess` was read: a half-open `[start, end)` range of Unicode code point offsets into `state_text` when present, else into `state`. For `text`, it covers exactly the guess. Computed values, and values read from images, have a `null` or absent span.
+- Lists are never `null` and keep input order. Text lists have `spans`, one entry per item: its span, or `null` for an item read from an image.
+- Estimates and every forecast step are within `[min, max]`, on the `step` grid, with `p10` ≤ `median` ≤ `p90`. A forecast has exactly `horizon` `steps`, nearest first. Estimates have `quantiles` only when their question sets `quantiles: true`; forecast steps never do.
+- `state_text`, the text the model read, is returned when it differs from `state`, for example for structured state. `truncated: true` means the model read only the start of the state.
+
+## System One caching
+
+Bkper caches System One results, for decision and extraction questions alike, for 15 minutes per user. An identical request in that window returns the same answers without calling the model or consuming allowance, and repeats the original `usage`. Aliases of the same model share one cache entry. To get fresh answers, change the request or wait. See [Privacy, retention, and caching](https://bkper.com/docs/ai/models#privacy-retention-and-caching).
+
 ## Stream a response
 
 Set `stream` to `true` to receive semantic server-sent events:
@@ -362,18 +436,19 @@ Unsupported fields fail explicitly rather than being ignored or passed to only o
 
 ## Errors
 
-Errors use an Open Responses-shaped envelope with stable Bkper error codes. `POST /v1/responses` and `POST /v1/decisions` normalize provider failures the same way. Branch on `error.code`, not only on the HTTP status, because `429` has two meanings.
+Errors use an Open Responses-shaped envelope with stable Bkper error codes. `POST /v1/responses` and `POST /v1/systemone` normalize provider failures the same way. Branch on `error.code`, not only on the HTTP status, because `429` has two meanings.
 
 | Status | Meaning                                                                         | `error.code` examples                                             | Retry                               |
 | ------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
 | `400`  | Invalid request, unavailable model, unsupported capability, or context overflow | `invalid_request`, `context_length_exceeded`, `provider_rejected` | No. Fix the field in `error.param`. |
+| `400`  | The selected model's provider does not serve the caller's region                | `provider_region_unsupported`                                     | No. Choose a model from another provider. |
 | `401`  | Missing or invalid Bkper bearer token                                           | `unauthorized`                                                    | No. Get a new Bkper token.          |
 | `402`  | The authenticated subscription payment is overdue                               | `billing_overdue`                                                 | No                                  |
 | `403`  | The account is not entitled to use Bkper AI                                     | `entitlement_unavailable`                                         | No                                  |
 | `429`  | The monthly Bkper AI allowance is exhausted                                     | `usage_limit_exceeded`                                            | No                                  |
 | `429`  | The upstream provider is throttled                                              | `provider_rate_limited`                                           | Yes, with backoff                   |
 | `499`  | The client aborted the request                                                  | `request_aborted`                                                 | —                                   |
-| `502`  | The selected upstream model provider or transport failed                        | `provider_error`, `provider_rejected`                             | A limited number of times           |
+| `502`  | The selected upstream model provider or transport failed                        | `provider_error`, `provider_rejected`, `provider_invalid_answer` | A limited number of times           |
 | `503`  | The provider is overloaded or quota usage is temporarily unavailable            | `provider_overloaded`, `usage_unavailable`                        | Yes, with backoff                   |
 
 When a provider sends `retry-after` with a `429` or `503`, Bkper AI forwards it; wait at least that long before retrying. `401` and `403` always refer to your Bkper token or account. Upstream provider credential problems surface as `502`.
@@ -392,7 +467,8 @@ Each operation has its own page. The machine-readable contract is [openapi.json]
 
 - [`POST /v1/responses` — Generate a response](https://bkper.com/docs/api/ai-gateway/operations/createresponse.md)
 
-### Decisions
+### System One
 
+- [`POST /v1/systemone` — Evaluate typed questions](https://bkper.com/docs/api/ai-gateway/operations/createsystemone.md)
 - [`POST /v1/decisions` — Evaluate typed questions](https://bkper.com/docs/api/ai-gateway/operations/createdecision.md)
 

package/lib/docs/api/managed-agent.md

@@ -107,6 +107,29 @@ the totals you checked.
 - A fork keeps its parent's instructions unless the create request sets new ones. Continuing someone else's session never takes theirs.
 - Sessions keep the text they were given. Updating your client changes only the sessions it creates or patches.
 
+### Agent context
+
+After your `instructions`, the agent reads its context: an `AGENTS.md` and skills (`.agents/skills/<name>/SKILL.md`) that people, the agent, or any other agent following the [AGENTS.md](https://agents.md/) and [Agent Skills](https://agentskills.io/specification) standards keep in a context repository per scope. A session loads the user's company's (their verified domain's, when they have one: shared by everyone in the domain, changed only by its admin), then the user's own, then its Book's (from its first input's `bookContext`, shared by everyone who can view the Book). Each is more specific than the one before and wins: a Book's skills replace the user's of the same name, and the user's the company's. It loads when the session starts and again at the start of each turn (an input that is not a steer or follow-up: a run never changes its context midway), each scope from the sandbox's working copy when the sandbox is running and the user or agent changed it there (local changes win, as on a local machine), else as published: the session's `contextScopes` show what loaded. When it changed, the agent is told so with that input. A fork starts with what its parent loaded.
+It loads as the person in every workspace, an App's included (such as a Slack bot's): permissions are the person's. Context of other Books never loads; the agent clones one only when asked.
+`GET /v1/skills?bookId=` lists the skills a session starting now could call by name, as published, before there is one.
+
+- Loading never delays a session by more than about two seconds: at the start, a scope that is slow or fails is skipped and shown as `unavailable`, never as an error in the conversation; at a turn, the session keeps all of what it had.
+- Context guides; it never grants anything. The user's messages override it, and it cannot relax Bkper's base.
+
+### Workspace
+
+The Workspace is the agent's computer as people see it: the working copies in the sandbox of the workspace you call through (the user's own, or your app's own for that user), the same files the agent sees, which both the user and the agent change. Nothing in them reaches anyone else, or any agent's context, until the user saves: Save publishes. Readers of shared sessions never reach someone else's.
+
+Repositories are named as one tree: `user` (the user's own context), `domain` (their company's, when they have a verified domain) and `books/{bookId}` (a Book's), the folders the sandbox and a local machine keep in `~/.bkper`, and `apps/{appId}` (the source of an App the user develops, in `/workspace/apps`). `GET /v1/workspace?bookId=` lists the root, as published: the user's domain, when they have one, the Book, named by Bkper, when the user can view it, and every App the user develops, those hosted elsewhere with their `repoUrl` instead of a repository. `GET /v1/workspace/status` reads every working copy in one call: its `fingerprint` (Git's tree id of its files, which changes whenever they do), its `base` (the published commit it builds on) and its marks (the files `added`, `modified` and `deleted` since the base, committed or not), plus the App folders in the sandbox, also those Bkper does not know yet. Opening a repository the sandbox does not have clones it there.
+
+- **Read**: a repository's files and marks (`canEdit` says whether the user may change and save it), one file's text and blob id (`version=base` for the base's), one PNG or JPEG picture's bytes (`/image`, at most 5 MiB, typed by its bytes).
+- **Change the working copy**: write a file over the version read (`previous`, the `sha` read: what changed since, such as by the agent, is 409 `file_changed`), move (rename) or delete a file or folder, add files from the user's computer (`/add`: 1 to 100 files at their full paths, each base64 of its exact bytes, a PNG or JPEG up to 5 MiB or text up to 256 KiB, at most 10 MiB together), undo a published commit (`/revert`), and discard changes (`/discard`: back to the base; a file never published goes). `POST /v1/workspace/copy` copies or moves a file or folder between two context repositories' working copies, such as into a Book from `GET /v1/workspace/books` (the Books whose context the user may change). A destination that exists is 409 `file_exists` (never overwritten; an add's lists every such file in `paths` at once, replaced only when it says `replace`), what cannot be written (a path, not text, too large) is 422 `file_invalid` with a `reason`; context may hold drafts agents would not load yet (the listing's `warnings` say so, and Save refuses them), and while Git works in the repository (the agent's, or a sync) 409 `workspace_busy`: nothing changed, try again.
+- **Review and save**: `/changes` shows everything Save would publish, each file before and after, with the working copy's `fingerprint`; `POST …/save` with that `fingerprint` publishes exactly what was reviewed: the agent's commits as they are (their messages and trailers in History), plus one commit of the rest, authored and committed by the user with an automatic message, never forced and never deployed. Changed since the review is 409 `review_stale`; someone published changes to the same lines meanwhile is 409 `publish_conflict`, naming the files (`paths`) and who published them (`publishers`), with nothing published and the working copy as before; an App Bkper does not know yet is 409 `app_unregistered` until the agent registers it.
+- **App secrets**: the secrets of an App's deployments on Bkper, production and preview, as `bkper app secrets` sets them, without the value ever reaching the agent or a conversation. `GET /v1/workspace/apps/{appId}/secrets` lists each deployment's names, or that the App is not deployed there yet; `PUT …/secrets/{name}?env=` with `{ "value" }` sets one (a name set again is replaced) and `DELETE` removes one, for the App's owner and developers (403 `workspace_forbidden`), only where it is deployed (409 `not_deployed`). Values are write-only. Only with the user's own token: through an app or channel bot these routes are 404.
+- **History**, as published: the latest 20 commits with the files each changed and whether each was made with the agent's help (`agent`: its message ends with the trailer `Assisted-by: Bkper Agent`; the user stays its author and committer), and what one of them changed (`/commit`, each file before and after).
+
+When the user changes the working copy, the agent is told which files with its next message. Context changed there applies to the user's sessions from their next turn while the sandbox runs; Save publishes it to everyone in its scope.
+
 ## Who the agent acts as
 
 Every request acts as the user whose token you send. That user's Book permissions and Bkper AI allowance apply.
@@ -323,6 +346,8 @@ Before the agent reads the input, each file is copied into its workspace, at `/w
 
 When the agent publishes a file, a `tool_result` entry carries a `file` part with `fileId`, `name`, `mediaType`, and `size`. List a session's published files with `GET /v1/sessions/{sessionId}/files`.
 
+In the user's own workspace, when the agent shows an App it is building running live (`show_app`), the `tool_result` entry carries a `live_app` part with the App's `appId`, `name`, and `menuUrl`, when it has one.
+
 ### Download, retention, and quotas
 
 - `GET /v1/files/{fileId}` returns the `File`; `GET /v1/files/{fileId}/content` its bytes, always as an attachment. The `Content-Type` is the allowlisted type for the name, never an upload's declared type; anything else is `application/octet-stream`.
@@ -455,6 +480,7 @@ A domain's admin can connect a service for everyone in the domain, with the same
 | `attributes` | 16 names, 16000 characters in total |
 | List page | 50 sessions, entries, or files |
 | Connected services | 20 per user and 20 per domain, 10 hosts each, tokens and keys up to 8192 characters, 20 Google scopes |
+| App secret value | 5 KiB |
 
 ## Errors
 
@@ -465,10 +491,10 @@ Errors are `{ "error": { "code", "type", "message" } }`. Branch on `code`.
 | 400 | `invalid_request`, `unknown_model`, `unknown_thinking_level` | A field is invalid or unknown |
 | 400 | `host_not_allowed` | A connected service names a host that has its own route, such as Bkper's or Google's token endpoint |
 | 401 | `unauthorized`, `authentication_failed` | The token is missing, invalid, or expired |
-| 403 | `agent_beta_required` | The account cannot use the agent, such as one without an email address |
 | 403 | `origin_forbidden` | A browser on another website sent a write |
 | 403 | `book_access_required` | The user cannot view the Book whose shared sessions they asked for |
 | 403 | `domain_admin_required` | Only the domain's admin changes its services |
+| 403 | `workspace_forbidden` | The user may not change or save this Workspace repository, or change this App's secrets |
 | 404 | `not_found`, `parent_not_found`, `file_not_found` | No such resource for this user |
 | 405 | `method_not_allowed` | The path does not support the method |
 | 409 | `idempotency_conflict` | The key was used with different content |
@@ -478,9 +504,14 @@ Errors are `{ "error": { "code", "type", "message" } }`. Branch on `code`.
 | 409 | `share_unavailable` | The session cannot be shared: an app's workspace, or outside a Book without a hosted domain |
 | 409 | `book_access_required` | The user cannot view the Book the session was started in |
 | 409 | `host_in_use`, `service_limit` | Another service holds the host, or the user (or domain) has 20 services |
+| 409 | `file_changed`, `file_exists` | A Workspace file changed since it was read, or a destination exists |
+| 409 | `workspace_busy` | Git is working in the Workspace repository; nothing changed, try again |
+| 409 | `not_deployed` | The App is not deployed to that environment: nothing to set there yet |
+| 409 | `review_stale`, `publish_conflict`, `app_unregistered` | Save: the files changed since the review, someone published changes to the same lines, or the App is not known to Bkper yet |
 | 410 | `file_gone` | The file's stored copy was deleted |
 | 411 | `length_required` | An upload has no `Content-Length` |
 | 413 | `request_too_large`, `file_too_large` | The JSON body exceeds 64 KiB, or the upload 25 MiB |
+| 422 | `file_invalid` | A Workspace change cannot be written or saved; `reason` says why |
 | 503 | `service_unavailable`, `authentication_failed` | A dependency is unavailable; retry with backoff |
 
 Model failures appear on the failed input and reply as `error.code`, such as `usage_limit_exceeded` when the monthly Bkper AI allowance is used up.
@@ -507,6 +538,7 @@ Each operation has its own page. The machine-readable contract is [openapi.json]
 - [`GET /v1/sessions/{sessionId}/entries/{entryId}` — Get a full entry](https://bkper.com/docs/api/managed-agent/operations/getentry.md)
 - [`POST /v1/sessions/{sessionId}/compact` — Compact earlier context](https://bkper.com/docs/api/managed-agent/operations/compactsession.md)
 - [`GET /v1/sessions/{sessionId}/export` — Export a session](https://bkper.com/docs/api/managed-agent/operations/exportsession.md)
+- [`GET /v1/skills` — List skills to call](https://bkper.com/docs/api/managed-agent/operations/listskills.md)
 
 ### Inputs
 
@@ -543,6 +575,68 @@ Each operation has its own page. The machine-readable contract is [openapi.json]
 - [`PUT /v1/domain/services/{serviceId}` — Connect or replace a domain service](https://bkper.com/docs/api/managed-agent/operations/putdomainservice.md)
 - [`DELETE /v1/domain/services/{serviceId}` — Disconnect a domain service](https://bkper.com/docs/api/managed-agent/operations/deletedomainservice.md)
 
+### Workspace
+
+- [`GET /v1/workspace` — Get the Workspace](https://bkper.com/docs/api/managed-agent/operations/getworkspace.md)
+- [`GET /v1/workspace/status` — Get the working copies' status](https://bkper.com/docs/api/managed-agent/operations/getworkspacestatus.md)
+- [`GET /v1/workspace/books` — List Books to copy to](https://bkper.com/docs/api/managed-agent/operations/listworkspacebooks.md)
+- [`POST /v1/workspace/copy` — Copy or move to another repository](https://bkper.com/docs/api/managed-agent/operations/copyworkspaceentry.md)
+- [`GET /v1/workspace/user` — Get a repository](https://bkper.com/docs/api/managed-agent/operations/getusercontext.md)
+- [`GET /v1/workspace/user/file` — Read a file](https://bkper.com/docs/api/managed-agent/operations/getusercontextfile.md)
+- [`PUT /v1/workspace/user/file` — Write a file](https://bkper.com/docs/api/managed-agent/operations/putusercontextfile.md)
+- [`GET /v1/workspace/user/image` — Read a picture](https://bkper.com/docs/api/managed-agent/operations/getusercontextimage.md)
+- [`GET /v1/workspace/user/history` — List history](https://bkper.com/docs/api/managed-agent/operations/listusercontexthistory.md)
+- [`GET /v1/workspace/user/commit` — Get a commit's changes](https://bkper.com/docs/api/managed-agent/operations/getusercontextcommit.md)
+- [`POST /v1/workspace/user/revert` — Undo a commit](https://bkper.com/docs/api/managed-agent/operations/revertusercontext.md)
+- [`POST /v1/workspace/user/move` — Move or rename a file or folder](https://bkper.com/docs/api/managed-agent/operations/moveusercontextentry.md)
+- [`POST /v1/workspace/user/delete` — Delete a file or folder](https://bkper.com/docs/api/managed-agent/operations/deleteusercontextentry.md)
+- [`POST /v1/workspace/user/add` — Add files](https://bkper.com/docs/api/managed-agent/operations/addusercontextfiles.md)
+- [`POST /v1/workspace/user/discard` — Discard changes](https://bkper.com/docs/api/managed-agent/operations/discardusercontext.md)
+- [`GET /v1/workspace/user/changes` — Review the changes](https://bkper.com/docs/api/managed-agent/operations/getusercontextchanges.md)
+- [`POST /v1/workspace/user/save` — Save](https://bkper.com/docs/api/managed-agent/operations/saveusercontext.md)
+- [`GET /v1/workspace/domain` — Get a repository](https://bkper.com/docs/api/managed-agent/operations/getdomaincontext.md)
+- [`GET /v1/workspace/domain/file` — Read a file](https://bkper.com/docs/api/managed-agent/operations/getdomaincontextfile.md)
+- [`PUT /v1/workspace/domain/file` — Write a file](https://bkper.com/docs/api/managed-agent/operations/putdomaincontextfile.md)
+- [`GET /v1/workspace/domain/image` — Read a picture](https://bkper.com/docs/api/managed-agent/operations/getdomaincontextimage.md)
+- [`GET /v1/workspace/domain/history` — List history](https://bkper.com/docs/api/managed-agent/operations/listdomaincontexthistory.md)
+- [`GET /v1/workspace/domain/commit` — Get a commit's changes](https://bkper.com/docs/api/managed-agent/operations/getdomaincontextcommit.md)
+- [`POST /v1/workspace/domain/revert` — Undo a commit](https://bkper.com/docs/api/managed-agent/operations/revertdomaincontext.md)
+- [`POST /v1/workspace/domain/move` — Move or rename a file or folder](https://bkper.com/docs/api/managed-agent/operations/movedomaincontextentry.md)
+- [`POST /v1/workspace/domain/delete` — Delete a file or folder](https://bkper.com/docs/api/managed-agent/operations/deletedomaincontextentry.md)
+- [`POST /v1/workspace/domain/add` — Add files](https://bkper.com/docs/api/managed-agent/operations/adddomaincontextfiles.md)
+- [`POST /v1/workspace/domain/discard` — Discard changes](https://bkper.com/docs/api/managed-agent/operations/discarddomaincontext.md)
+- [`GET /v1/workspace/domain/changes` — Review the changes](https://bkper.com/docs/api/managed-agent/operations/getdomaincontextchanges.md)
+- [`POST /v1/workspace/domain/save` — Save](https://bkper.com/docs/api/managed-agent/operations/savedomaincontext.md)
+- [`GET /v1/workspace/books/{bookId}` — Get a repository](https://bkper.com/docs/api/managed-agent/operations/getbookcontext.md)
+- [`GET /v1/workspace/books/{bookId}/file` — Read a file](https://bkper.com/docs/api/managed-agent/operations/getbookcontextfile.md)
+- [`PUT /v1/workspace/books/{bookId}/file` — Write a file](https://bkper.com/docs/api/managed-agent/operations/putbookcontextfile.md)
+- [`GET /v1/workspace/books/{bookId}/image` — Read a picture](https://bkper.com/docs/api/managed-agent/operations/getbookcontextimage.md)
+- [`GET /v1/workspace/books/{bookId}/history` — List history](https://bkper.com/docs/api/managed-agent/operations/listbookcontexthistory.md)
+- [`GET /v1/workspace/books/{bookId}/commit` — Get a commit's changes](https://bkper.com/docs/api/managed-agent/operations/getbookcontextcommit.md)
+- [`POST /v1/workspace/books/{bookId}/revert` — Undo a commit](https://bkper.com/docs/api/managed-agent/operations/revertbookcontext.md)
+- [`POST /v1/workspace/books/{bookId}/move` — Move or rename a file or folder](https://bkper.com/docs/api/managed-agent/operations/movebookcontextentry.md)
+- [`POST /v1/workspace/books/{bookId}/delete` — Delete a file or folder](https://bkper.com/docs/api/managed-agent/operations/deletebookcontextentry.md)
+- [`POST /v1/workspace/books/{bookId}/add` — Add files](https://bkper.com/docs/api/managed-agent/operations/addbookcontextfiles.md)
+- [`POST /v1/workspace/books/{bookId}/discard` — Discard changes](https://bkper.com/docs/api/managed-agent/operations/discardbookcontext.md)
+- [`GET /v1/workspace/books/{bookId}/changes` — Review the changes](https://bkper.com/docs/api/managed-agent/operations/getbookcontextchanges.md)
+- [`POST /v1/workspace/books/{bookId}/save` — Save](https://bkper.com/docs/api/managed-agent/operations/savebookcontext.md)
+- [`GET /v1/workspace/apps/{appId}` — Get a repository](https://bkper.com/docs/api/managed-agent/operations/getappsource.md)
+- [`GET /v1/workspace/apps/{appId}/file` — Read a file](https://bkper.com/docs/api/managed-agent/operations/getappsourcefile.md)
+- [`PUT /v1/workspace/apps/{appId}/file` — Write a file](https://bkper.com/docs/api/managed-agent/operations/putappsourcefile.md)
+- [`GET /v1/workspace/apps/{appId}/image` — Read a picture](https://bkper.com/docs/api/managed-agent/operations/getappsourceimage.md)
+- [`GET /v1/workspace/apps/{appId}/history` — List history](https://bkper.com/docs/api/managed-agent/operations/listappsourcehistory.md)
+- [`GET /v1/workspace/apps/{appId}/commit` — Get a commit's changes](https://bkper.com/docs/api/managed-agent/operations/getappsourcecommit.md)
+- [`POST /v1/workspace/apps/{appId}/revert` — Undo a commit](https://bkper.com/docs/api/managed-agent/operations/revertappsource.md)
+- [`POST /v1/workspace/apps/{appId}/move` — Move or rename a file or folder](https://bkper.com/docs/api/managed-agent/operations/moveappsourceentry.md)
+- [`POST /v1/workspace/apps/{appId}/delete` — Delete a file or folder](https://bkper.com/docs/api/managed-agent/operations/deleteappsourceentry.md)
+- [`POST /v1/workspace/apps/{appId}/add` — Add files](https://bkper.com/docs/api/managed-agent/operations/addappsourcefiles.md)
+- [`POST /v1/workspace/apps/{appId}/discard` — Discard changes](https://bkper.com/docs/api/managed-agent/operations/discardappsource.md)
+- [`GET /v1/workspace/apps/{appId}/changes` — Review the changes](https://bkper.com/docs/api/managed-agent/operations/getappsourcechanges.md)
+- [`POST /v1/workspace/apps/{appId}/save` — Save](https://bkper.com/docs/api/managed-agent/operations/saveappsource.md)
+- [`GET /v1/workspace/apps/{appId}/secrets` — List an App's secrets](https://bkper.com/docs/api/managed-agent/operations/listappsecrets.md)
+- [`PUT /v1/workspace/apps/{appId}/secrets/{name}` — Set an App's secret](https://bkper.com/docs/api/managed-agent/operations/putappsecret.md)
+- [`DELETE /v1/workspace/apps/{appId}/secrets/{name}` — Delete an App's secret](https://bkper.com/docs/api/managed-agent/operations/deleteappsecret.md)
+
 ### Models
 
 - [`GET /v1/models` — List models](https://bkper.com/docs/api/managed-agent/operations/listmodels.md)