bkper 5.8.0 → 5.8.2

package/lib/docs/apps/ai.md

@@ -6,7 +6,8 @@ Model output is a suggestion, not permission to change a Book. Keep decisions ab
 
 ## Choose the kind of response
 
-- **A yes/no, a choice, or a level on a scale?** Ask a decision model, such as `jev`, with TypeSafe's SDK, `@typesafe-ai/sdk`.
+- **A judgment: a yes/no, one of known options, or a level on a scale?** [Ask a System One model](#ask-a-system-one-model) a decision question, with a model such as `jev`.
+- **A value read from a document, such as an invoice total, or a likely range for an uncertain number, such as days until an invoice is paid?** [Ask a System One model](#ask-a-system-one-model) an extraction question, with a model such as `clairic`.
 - **Text or a custom JSON object?** Ask a language model (LLM), such as `gpt-luna`, with AI SDK's Open Responses provider, `@ai-sdk/open-responses`.
 - **A conversation that works on Books?** Reading and comparing Books, computing with scripts, delivering files, remembering earlier messages: [run an agent](#run-an-agent) with the Managed Agent API instead of calling a model.
 
@@ -35,10 +36,19 @@ The client can call Bkper AI directly with `auth.authenticatedFetch()`, which se
 
 In both cases usage counts against the user's allowance. See [Call from a browser](https://bkper.com/docs/api/ai-gateway.md#call-from-a-browser) for a request example.
 
-## Ask a decision model
+## Ask a System One model
+
+Every System One question, decision or extraction, goes to `POST /v1/systemone`. There are two ways to send it:
+
+- **TypeSafe's SDK**, `@typesafe-ai/sdk`, types decision questions and their answers for you. It does not send extraction questions or images.
+- **`fetch`** sends any question type, and images.
+
+Bkper AI validates every answer against its question before responding, so your code can use it directly. Keep the questions, the thresholds, and the function that turns answers and facts into an action in one module.
+
+### With TypeSafe's SDK
 
 ```ts
-import { score, TypeSafeClient } from '@typesafe-ai/sdk';
+import { noul, TypeSafeClient } from '@typesafe-ai/sdk';
 
 const decisionClient = new TypeSafeClient({
     apiKey: 'bkper-platform-outbound',
@@ -46,26 +56,69 @@ const decisionClient = new TypeSafeClient({
     defaultModel: 'jev',
 });
 
-export async function scoreRecurring(description: string) {
+export async function recurringProbability(description: string): Promise<number> {
     const { answers } = await decisionClient.systemOne({
         state: { description },
         questions: {
-            recurring: score('How likely is this a recurring charge?', [
-                'Unlikely',
-                'Possible',
-                'Likely',
-            ]),
+            recurring: noul('Is this a recurring charge, such as a subscription or a monthly bill?'),
         },
     });
-    return answers.recurring;
+    return answers.recurring.noul;
 }
 ```
 
 - **`apiKey`** is required by the SDK. In a Platform Worker, pass any placeholder: platform outbound replaces it with the user's authorization.
 - **`baseURL`** has no `/v1`. The SDK calls `POST /v1/systemone`, which behaves exactly like `POST /v1/decisions`.
-- **The answer is typed** from the question. Bkper AI validates every answer against its question before responding, so your code can use it directly.
+- **The answer is typed** from the question: here, `noul` is the probability of yes, which your code compares with a threshold.
+
+### With fetch
+
+```ts
+interface ValueAnswer {
+    value: T | null;
+    guess?: T;
+    p_null: number;
+    confidence: number;
+}
+
+interface InvoiceReading {
+    model: string;
+    answers: { total: ValueAnswer<number>; issue_date: ValueAnswer<string> };
+    truncated?: boolean;
+}
+
+interface BkperAiErrorBody {
+    error: { code: string; message: string };
+}
+
+export async function readInvoice(email: string): Promise {
+    // No Authorization header: the platform adds the user's.
+    const response = await fetch('https://ai.bkper.app/v1/systemone', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            model: 'clairic',
+            state: email,
+            questions: {
+                total: { type: 'number', decimals: 2, instructions: 'Invoice total' },
+                issue_date: { type: 'date', instructions: 'Invoice issue date' },
+            },
+        }),
+    });
+    if (!response.ok) {
+        const { error } = (await response.json()) as BkperAiErrorBody;
+        throw new Error(`${error.code}: ${error.message}`);
+    }
+    // Bkper AI validated each answer against its question.
+    return (await response.json()) as InvoiceReading;
+}
+```
+
+- **`value` can be `null`** when the email probably lacks it. Send such items, and any response with `truncated: true`, to a person with the `guess`.
+- **The model reads; code checks.** Compare the total with the invoice lines, and compute dates such as the due date, before anything reaches a Book.
+- **Images** go in the same request, as base64 `assets`.
 
-[Decision Models](https://bkper.com/docs/ai/decision-models.md) covers designing the questions, facts, and thresholds; the [AI Gateway API](https://bkper.com/docs/api/ai-gateway.md#decision-models) covers the request, answers, errors, and caching. The open-source [Merge Duplicates app](https://github.com/bkper/bkper-apps/tree/main/merge-duplicates) uses this setup to suggest duplicate pairs for human review.
+[System One Models](https://bkper.com/docs/ai/system-one-models.md) covers designing the questions, facts, and thresholds, and every question type; the [AI Gateway API](https://bkper.com/docs/api/ai-gateway.md#decision-questions) covers the request, answers, errors, and caching. The open-source [Merge Duplicates app](https://github.com/bkper/bkper-apps/tree/main/merge-duplicates) uses TypeSafe's SDK to suggest duplicate pairs for human review.
 
 ## Generate a language response
 
@@ -98,7 +151,7 @@ Keep schemas simple. Constraints such as a string's minimum or maximum length ma
 
 ## Run an agent
 
-For a chat that does real work on Books, start a session on the [Managed Agent API](https://bkper.com/docs/api/managed-agent.md) from the app's server. Bkper runs the agent in the user's private cloud workspace, with the `bkper` CLI, files, and durable sessions. Your app keeps its screens, prompts, and instructions. The Managed Agent is in beta.
+For a chat that does real work on Books, start a session on the [Managed Agent API](https://bkper.com/docs/api/managed-agent.md) from the app's server. Bkper runs the agent in the user's private cloud workspace, with the `bkper` CLI, files, and durable sessions. Your app keeps its screens, prompts, and instructions.
 
 ```ts
 // No Authorization header: the platform adds the user's.
@@ -123,6 +176,7 @@ const session = await response.json();
 Then follow the session's stream, or poll the input until it completes, as in the [quick start](https://bkper.com/docs/api/managed-agent.md#quick-start).
 
 - **The user's agent.** Sessions belong to the user, so work started in your app continues in Bkper Agent or any other app.
+- **The user's procedures.** The agent follows the user's [agent context](https://bkper.com/docs/ai/agent-context.md): their company's, their own, and the session's Book's, loaded after your instructions.
 - **Your services as tools.** The agent can call your app's API as the user. Describe the routes in your instructions, and the agent can run your checks instead of redoing them.
 - **Real changes.** Unlike a model call, the agent can change Books with the user's permissions. Say in your instructions when it may.
 
@@ -174,6 +228,7 @@ Every Bkper AI error has the same envelope: `{ error: { message, type, param, co
 
 - **TypeSafe SDK:** an `APIError` with `status` and the envelope in `body`, so read `error.body.error.code`. Network failures and timeouts throw `APIConnectionError`.
 - **AI SDK:** an `APICallError` with `statusCode` and the envelope in `data`, so read `error.data.error.code`. Output that does not match your schema throws `NoObjectGeneratedError`.
+- **`fetch`:** a response that is not `ok` has the envelope as its JSON body. `fetch` does not retry.
 
 Both SDKs retry rate limits and server errors twice by default. A failed attempt costs nothing: Bkper AI charges only successful answers.
 
@@ -183,7 +238,7 @@ Map these errors to your route's typed error response. Keep the code and message
 
 - **Passing your own `fetch`.** The TypeSafe SDK calls `fetch` as its own method, which the Workers runtime rejects with `Illegal invocation`. Wrap it: `fetch: (input, init) => myFetch(input, init)`. Without the option, the SDK's default works.
 - **No `null` values.** The TypeSafe SDK's types accept `null` for state, instructions, and some criteria. Bkper AI rejects them with `400`.
-- **No SDK image uploads.** The TypeSafe SDK uploads images as multipart, which Bkper AI rejects with `400`. Send image requests with `fetch` as JSON, with base64 `assets`. See [Decision Models](https://bkper.com/docs/ai/decision-models.md#jev-by-typesafe).
+- **No SDK image uploads.** The TypeSafe SDK uploads images as multipart, which Bkper AI rejects with `400`. Send image requests [with `fetch`](#with-fetch) as JSON, with base64 `assets`. See [System One Models](https://bkper.com/docs/ai/system-one-models.md#models) for each model's image limits.
 - **No `client.models.list()`.** It expects TypeSafe's catalog shape. Use the [`GET /v1/models`](https://ai.bkper.app/v1/models) catalog.
 - **Other System One clients** take `https://ai.bkper.app/v1` as their base URL.
 - **Flexible JSON schemas.** Open Responses always requests `strict: true`. For a schema that needs `strict: false`, such as a typed dynamic map, use `@ai-sdk/openai` with base URL `https://ai.bkper.app/v1`, its `.responses()` model, and `strictJsonSchema: false`.
@@ -192,11 +247,12 @@ Map these errors to your route's typed error response. Keep the code and message
 
 - **Send only task-relevant data.** Validate input and Book permissions at the app API boundary.
 - **Keep writes deterministic.** An answer or generated text must not create, merge, or alter a Transaction without application rules and any required human confirmation.
+- **Test the decision without the model.** Unit-test the function that turns answers and facts into an action with fixed answers, just below and just above each threshold.
 - **Test the service.** Mock `fetch` and check what is sent, that the Worker adds no user token, and that errors stay actionable. Then run the app's normal check and build.
 
 ## Next steps
 
-- [Decision Models](https://bkper.com/docs/ai/decision-models.md): questions, answers, thresholds, and caching.
+- [System One Models](https://bkper.com/docs/ai/system-one-models.md): decision and extraction questions, answers, and thresholds.
 - [Models and Usage](https://bkper.com/docs/ai/models.md): models, usage rates, the allowance, and privacy.
 - [AI Gateway API](https://bkper.com/docs/api/ai-gateway.md): tokens, raw HTTP requests, capabilities, and errors.
 - [Managed Agent API](https://bkper.com/docs/api/managed-agent.md): sessions, instructions, files, and streams.

package/lib/docs/apps/configuration.md

@@ -113,8 +113,9 @@ The following variables can be used in `menuUrl` and `menuUrlDev`:
 | `${group.id}`               | Selected group ID                        |
 | `${group.name}`             | Selected group name                      |
 | `${group.properties.xxx}`   | Group property value                     |
-| `${transactions.ids}`       | Comma-separated selected transaction IDs |
+| `${transactions.ids}`       | Space-separated selected transaction IDs |
 | `${transactions.query}`     | Current search query                     |
+| `${app.state}`              | The App's state in the Book URL, URL-encoded; empty without one. See [Keeping state in the Book URL](https://bkper.com/docs/platform/apps/context-menu.md#keeping-state-in-the-book-url). |
 
 ### Event handling
 

package/lib/docs/apps/context-menu.md

@@ -114,7 +114,7 @@ Each time the App iframe finishes loading, Bkper announces the requests it suppo
 ```js
 {
     type: 'bkper:host-ready',
-    supports: ['navigate', 'show-book', 'expand', 'login'],
+    supports: ['navigate', 'show-book', 'expand', 'login', 'app-state'],
 }
 ```
 
@@ -124,6 +124,7 @@ Send each request only after receiving this message with its name in `supports`:
 - `bkper:show-book` with `show-book`.
 - `bkper:expand` with `expand`.
 - `bkper:login` with `login`.
+- `bkper:app-state` with `app-state`.
 
 Until then, keep the normal link behavior. Register the message listener when the App starts, so it does not miss the message.
 
@@ -247,6 +248,144 @@ Bkper ignores the message when it does not come from the App iframe currently op
 
 Bkper does not reply.
 
+#### Keeping state in the Book URL
+
+An App can keep a short state in the Book's URL, such as the report or item open in it. Reloading the Book, going Back, or opening a shared link of the Book then opens the App where the user left it:
+
+```js
+window.parent.postMessage({ type: 'bkper:app-state', state: 'expenses-2025' }, BKPER_ORIGIN);
+```
+
+Bkper keeps the state as `appState`, next to the App's id in `app`:
+
+```
+https://bkper.app/books/abc123/transactions?app=my-app&appState=expenses-2025
+```
+
+Bkper ignores the message when any of these is true:
+
+- It does not come from the App iframe currently open in the panel.
+- It does not come from that iframe's own origin.
+- `app` in the Book URL names another App.
+- `state` is not a string of at most 128 letters (`A–Z`, `a–z`), digits, `_` or `-`.
+
+For a valid request, Bkper replaces `appState` in the Book URL without reloading Bkper or the App and without adding a history entry, so Back stays the Book's. An empty `state` removes it. Bkper does not reply.
+
+The App reads its state back through the [`${app.state}`](#available-expressions) expression of its menu URL:
+
+```yaml
+menuUrl: https://my-app.bkper.app?bookId=${book.id}&state=${app.state}
+```
+
+- **Opening a Book URL that names the App and its state**, such as from a link, Back, or a reload, opens the App with that state in its URL. When the App is already open, it receives the new URL in [`bkper:app-url-changed`](#live-context-updates) instead.
+- **After a valid `bkper:app-state` that changes the App's URL**, such as a new state with `${app.state}` in its menu URL, the App receives `bkper:app-url-changed` with the state it just sent. Treat it as its own state, not a new place.
+- **Opening the App from the menu, opening another App, or closing the App** removes `appState`.
+
+The state is opaque to Bkper and visible in the Book's URL:
+
+- Keep it a short reference, such as an id, not data.
+- Anyone can write a link with any `appState`. Validate it, and treat a state the App does not recognize as no state.
+- Older Bkper versions leave `${app.state}` in the URL unreplaced. Treat it, an empty value, or a missing one as no state.
+
+### Files in Bkper Agent
+
+Bkper Agent shows the HTML files it delivers, such as a report an App's API returns for the agent, beside the conversation. Each file runs in a sandboxed frame:
+
+- **An `<iframe sandbox="allow-scripts">` with the file as its `srcdoc`.** The frame's origin is opaque (`null`), so the file cannot reach Bkper, the Agent, or their sessions.
+- **A Content Security Policy ahead of the file's own content**: `default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; media-src data: blob:; form-action 'none'; base-uri 'none'`. Scripts and styles must be inline, and images, fonts, and media `data:` or `blob:` URLs. The file reaches no network.
+- **Up to 1 MB.** Larger HTML files only download.
+
+A file can use one request of the Bkper page around the Agent: `bkper:navigate`, such as for an **Open in** link that replaces the Agent with an App in the same panel and Book.
+
+#### File host support
+
+Each time the file's frame finishes loading, while the Agent is open in a Bkper panel that accepts navigation, the Agent tells the file:
+
+```js
+{
+    type: 'bkper:host-ready',
+    supports: ['navigate'],
+    origin: 'https://bkper.app',
+}
+```
+
+- `origin` is the Bkper origin to link to. The message's `event.origin` is the Agent's, such as `https://agent.bkper.app`, because the Agent hosts the file, not Bkper.
+- When Bkper starts accepting navigation after the file loaded, the Agent tells the file again.
+- When the Agent is not in a Bkper panel that accepts navigation, such as the Agent opened on its own, the Agent sends nothing. Keep links as plain links that open a new tab.
+
+#### Requesting navigation from a file
+
+Post the Bkper URL to the Agent, at the `event.origin` of its `bkper:host-ready`:
+
+```js
+window.parent.postMessage(
+    {
+        type: 'bkper:navigate',
+        url: 'https://bkper.app/books/abc123/transactions?app=my-app&appState=expenses-2025',
+    },
+    agentOrigin
+);
+```
+
+The Agent ignores the message silently unless all of these are true:
+
+- It comes from the file's own frame.
+- That frame has focus: the user is interacting with the file, such as by clicking in it.
+- `url` is an absolute Bkper URL with no username or password, as for a link in the agent's replies.
+- The Agent is open in a Bkper panel that accepts navigation.
+
+Then the Agent asks Bkper to navigate, as when the user clicks a link in the conversation:
+
+- **A Book page that names an App and its state** (`app` and `appState`): Bkper opens that App with that state, if the App is installed in that Book. When the Agent is open in a Book, the App replaces it in the same panel, without reloading Bkper.
+- **A Book page without `app`**: Bkper navigates to it and the Agent stays open.
+- **Other Bkper pages**: Bkper loads the page as a normal navigation.
+
+Neither the Agent nor Bkper replies.
+
+Send `bkper:navigate` only in response to a user action, such as a click. The focus rule keeps a file from navigating as it loads, but the frame keeps focus after a click, so the Agent cannot tell a click from a later request.
+
+#### File example
+
+Keep the link a real link to the App that opens in a new tab, so it works wherever navigation is not available:
+
+```html
+<a id="open-in-app" href="https://my-app.bkper.app?bookId=abc123&state=expenses-2025" target="_blank">
+    Open in My App
+</a>
+```
+
+Then turn a plain click into a navigation request once the Agent supports it:
+
+```js
+let host; // The Bkper origin to link to, and the Agent's origin to post to.
+
+window.addEventListener('message', event => {
+    // Only the window around the file, the Agent, tells it what it may ask.
+    if (event.source !== window.parent) return;
+
+    const message = event.data;
+    if (message?.type !== 'bkper:host-ready' || !Array.isArray(message.supports)) return;
+    host =
+        message.supports.includes('navigate') && typeof message.origin === 'string'
+            ? { bkper: message.origin, agent: event.origin }
+            : undefined;
+});
+
+document.getElementById('open-in-app').addEventListener('click', event => {
+    // Keep modified and non-primary clicks as normal links, such as opening a new tab.
+    if (!host || event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+    event.preventDefault();
+    const url = new URL('/books/abc123/transactions', host.bkper);
+    url.searchParams.set('app', 'my-app');
+    url.searchParams.set('appState', 'expenses-2025');
+    window.parent.postMessage({ type: 'bkper:navigate', url: url.href }, host.agent);
+});
+```
+
+The file cannot verify the Bkper origin itself. It posts only to the window that sent `bkper:host-ready`, and the Agent checks the URL again.
+
 ### Available expressions
 
 The menu URL supports these dynamic expressions:
@@ -259,5 +398,6 @@ The menu URL supports these dynamic expressions:
 | `${account.name}`       | The selected account name |
 | `${group.id}`           | The selected group ID     |
 | `${group.name}`         | The selected group name   |
+| `${app.state}`          | The App's state in the Book URL, URL-encoded; empty without one. See [Keeping state in the Book URL](#keeping-state-in-the-book-url). |
 
 For the full list of accepted expressions, see the [Menu URL variables](https://bkper.com/docs/platform/apps/configuration.md#menu-url-variables) reference.

package/lib/docs/apps/development.md

@@ -115,6 +115,33 @@ bkper app build
 4. Trigger events in Bkper and inspect handler responses in the activity stream.
 5. Run `npm run check` before considering the change complete.
 
+## Develop with Bkper Agent
+
+[Bkper Agent](https://bkper.com/docs/ai/bkper-agent/build-apps.md) can build and change your app in its cloud workspace, and show it live beside the conversation. There, `bkper app dev` runs without `bkper auth login`: the workspace adds the person's credentials to the app's calls to Bkper.
+
+To show live, an app needs:
+
+- **Bkper CLI 5.8.0 or later** in its lockfile.
+- **The template's current Vite config**, which accepts the live host the agent sets in `BKPER_LIVE_HOST`:
+
+```ts
+// client/vite.config.ts
+export default defineConfig(() => {
+    const liveHost = process.env.BKPER_LIVE_HOST;
+    return {
+        // ...
+        server: {
+            // ...
+            ...(liveHost
+                ? { allowedHosts: [liveHost] }
+                : { hmr: { host: 'localhost', port: 5173, clientPort: 5173 } }),
+        },
+    };
+});
+```
+
+The events tunnel does not run in the agent's workspace, and only the person's browser reaches the live app. Test event handlers and integrations on a preview with `bkper app deploy --preview`.
+
 ## Debugging
 
 - **Server errors** — Check the terminal output from `bkper app dev`. Worker runtime errors appear here.

package/lib/docs/apps/overview.md

@@ -21,7 +21,7 @@ The same Worker can expose app-defined `/api/*` routes. Treat those routes as th
 Apps call Bkper AI models through the AI gateway, with no provider accounts or keys:
 
 - **Language models** — multi-provider models over the Open Responses protocol, for text and structured output.
-- **Decision models** — typed answers with calibrated confidence: yes or no, one of your options, or a level on a scale.
+- **System One models** — typed answers with calibrated confidence: judgments, such as yes or no, one of your options, or a level on a scale; values read from documents, such as an invoice total; and estimates of uncertain numbers. Your code decides what to do with them.
 
 Usage counts against the user's included Bkper AI allowance. An authenticated app API route or event establishes the user and app identity, and the platform adds authorization and usage attribution to the Worker's requests. For inference used only by the UI, the client can also call Bkper AI directly with the signed-in user's token.
 

package/lib/docs/apps/quality.md

@@ -64,7 +64,7 @@ Start every client with this structure, so it grows by adding pieces instead of
 - **Components render and report intent.** A component watches only the stores it shows and changes them only through their actions, in response to the person, never while rendering. Only its own presentation, such as an open menu or hover, stays in the component. Each component owns its CSS.
 - **Stores ask the interface through events.** When a store needs the interface to act, such as focusing an input or scrolling to new content, it fires an event the component listens to. Stores never call components.
 - **One module wires the stores.** It creates them and gives each the stores it depends on. Dependencies point one way. A store changes another store only through that store's actions, and reactions that span stores live in this module. Components get only the stores and actions they use; services stay inside this module.
-- **One module owns the URL.** Only it reads or writes the URL's path, query, and `history`, mapping the URL to state. Put in the URL what a person would reload or share, such as the selected item. Standalone, add a history entry for each place the person goes, so Back works; when a place becomes another, such as a new item once saved, replace its entry. Embedded in a Book, replace the URL so Back stays the Book's. Pass it the window so it can be tested.
+- **One module owns the URL.** Only it reads or writes the URL's path, query, and `history`, mapping the URL to state. Put in the URL what a person would reload or share, such as the selected item. Standalone, add a history entry for each place the person goes, so Back works; when a place becomes another, such as a new item once saved, replace its entry. Embedded in a Book, replace the URL so Back stays the Book's, and keep what a person would reload or share in the Book's URL with [`bkper:app-state`](https://bkper.com/docs/platform/apps/context-menu.md#keeping-state-in-the-book-url). Pass it the window so it can be tested.
 - **Split by concern, not by screen region.** Split a store or component when its parts change for different reasons.
 
 ## Security

package/lib/docs/core/core-concepts.md

@@ -129,7 +129,7 @@ Bkper maintains a continuous ledger with no concept of closing periods — the s
 
 ## Custom Properties
 
-**Custom Properties** are key-value pairs attachable to any entity — Books, Accounts, Groups, Transactions, Collections, and Files. They add context, metadata, and meaning beyond core financial data.
+**Custom Properties** are key-value pairs attachable to any entity — Books, Accounts, Groups, Transactions, and Files. They add context, metadata, and meaning beyond core financial data.
 
 By attaching properties like `invoice: inv123456` or `exc_code: BRL`, entities become rich with information that can drive automation and reporting — without changing the core model.
 

package/lib/docs/index.md

@@ -8,9 +8,9 @@ For Bkper app implementation, refactoring, or code review, always read `apps/qua
 - `cli/app-usage.md` — Using Bkper apps to do work on a Book instead of rebuilding what they do: list a Book's installed apps and the app catalog, read descriptions, readmes, and property schemas, match them to the Book's properties, read an app's OpenAPI spec and call its API as the user, install apps.
 - `cli/app-management.md` — CLI reference for building and deploying Bkper apps: init/git clone/credential helpers, dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
 - `apps/overview.md` — Platform evaluation and capability overview: use when comparing managed Bkper hosting with self-managed infrastructure or clarifying platform responsibilities; use the task-specific app references for implementation.
-- `apps/ai.md` — Bkper AI in apps, scripts, and tools: ask the Jev decision model with TypeSafe's SDK or language models with AI SDK Open Responses, authenticate through app `/api/*` routes or a Bkper token outside the platform, handle errors, and keep Book writes under deterministic application control.
-- `ai/decision-models.md` — Designing software around decision models: when to use one, the three kinds of question, a step-by-step workflow from facts to thresholds and human review, and a worked bank-line example. The request, answers, errors, and caching are in `api/ai-gateway.md`.
-- `api/ai-gateway.md` — Bkper AI Gateway API guide: call Bkper AI language and decision models from your own client, script, or server — authentication, model IDs, requests, decision request rules and answer guarantees, streaming, errors, caching, and links to each operation's page.
+- `apps/ai.md` — Bkper AI in apps, scripts, and tools: ask System One models such as Jev or Clairic, with TypeSafe's SDK for decision questions or `fetch` for any question type, or language models with AI SDK Open Responses, authenticate through app `/api/*` routes or a Bkper token outside the platform, handle errors, and keep Book writes under deterministic application control.
+- `ai/system-one-models.md` — Designing software around System One models: decision questions (Jev, Clef) for yes/no, choice, and score judgments, and extraction questions (Clairic, preview) for values read from documents, with spans, nulls, and estimates. Covers when to use each, the rule that models read and judge while code calculates and decides, a workflow that sorts each condition into code facts and one-judgment questions and combines them in code with thresholds and human review, and worked bank-line and supplier-email examples. The request, answers, errors, and caching are in `api/ai-gateway.md`.
+- `api/ai-gateway.md` — Bkper AI Gateway API guide: call Bkper AI language and System One models from your own client, script, or server — authentication, model IDs, requests, System One request rules and answer guarantees, streaming, errors, caching, and links to each operation's page.
 - `api/managed-agent.md` — Bkper Managed Agent API guide: build apps, chat bots, and scripts on the agent behind Bkper Agent — sessions, instructions, inputs and idempotency, Book context, streams, files, a Slack bot example, limits, errors, and links to each operation's page.
 - `apps/first-app.md` — First-app walkthrough: scaffold, install, run locally, trigger an event, customize the listing, establish shared source, check, and deploy.
 - `apps/architecture.md` — App and template architecture: npm workspace structure, Lit/Vite client, Hono Worker, typed `/api/*` contracts, authentication, `/events`, static assets, and supported app shapes.
@@ -21,7 +21,7 @@ For Bkper app implementation, refactoring, or code review, always read `apps/qua
 - `apps/event-handlers.md` — Event handler behavior: `/events` routing, responses, replay, loop prevention, platform and self-hosted authentication, event payloads, and event types.
 - `apps/deploying.md` — Build, sync, and explicit deploy workflow; production and preview environments, secrets, KV, deployment status, and book installation.
 - `apps/shared-app-source.md` — Bkper-managed private Git source: developer access, first sync, clone workflow, source/deployment separation, safety checks, external remotes, and monorepos.
-- `apps/context-menu.md` — Book context-menu integration: production/development URLs, open modes, and dynamic Book, query, Account, and Group expressions.
+- `apps/context-menu.md` — Book context-menu integration: production/development URLs, open modes, dynamic Book, query, Account, Group, and App-state expressions, live context updates, keeping App state in the Book URL, and HTML files shown in Bkper Agent (sandbox, size limit, navigation requests).
 - `apps/app-listing.md` — App listing metadata, visibility, publication review, end-user README guidance, and public listing locations.
 - `apps/self-hosted.md` — Self-hosted event-handler alternatives: Cloud Functions, generic webhooks, direct authentication responsibilities, scaling, responses, and retries.
 - `reporting/financial-statements.md` — Deterministic reporting principles and Bkper query semantics for balance sheet and P&L: trusted routes, root reporting groups, permanent vs period date rules, and provisional query patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "5.8.0",
+    "version": "5.8.2",
     "description": "Official Bkper CLI for accounting data, automation, apps, and AI agents",
     "bin": {
         "bkper": "lib/cli.js"

package/lib/docs/ai/decision-models.md

@@ -1,158 +0,0 @@
-# Decision Models
-
-A decision model judges; your code decides. It reads the facts your code gives it, such as a bank line, and answers narrow questions in a shape you set in advance: how likely something is true, which of your options fits, or where it sits on your scale. It writes no text, and it reports how sure it is as a number your code can compare.
-
-Why that suits accounting is covered in [AI Fundamentals](https://bkper.com/docs/ai/fundamentals.md#decision-models). This page is about designing with decision models. [Jev](#jev-by-typesafe), by TypeSafe, is Bkper's first.
-
-## When to use one
-
-| Your software needs                                              | Use                                                                                                        |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| A yes or no, one of known options, or a level on a scale         | A decision model                                                                                           |
-| Text, explanations, code, tool calls, or a custom JSON object    | A [language model](https://bkper.com/docs/ai/models.md)                                                                        |
-| A conversation that works on Books, computes, and delivers files | An agent: [Bkper Agent](https://bkper.com/docs/ai/bkper-agent.md), or the [Managed Agent API](https://bkper.com/docs/api/managed-agent.md) in your app |
-
-## Where you use them
-
-- **In [Bkper CLI Agent](https://bkper.com/docs/ai/bkper-cli-agent.md#what-it-can-do)**, with no setup. Describe the outcome, such as "suggest Accounts for these bank lines and show me only the unsure ones", and the agent asks the decision model for you.
-- **In apps and scripts**, with TypeSafe's SDK. See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai.md#ask-a-decision-model). The open-source [Merge Duplicates app](https://github.com/bkper/bkper-apps/tree/main/merge-duplicates) uses one to suggest duplicate pairs for a person to review.
-
-## Three kinds of question
-
-Each question gets one typed answer:
-
-| Ask                                | Example                                       | You get                                              |
-| ---------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
-| **Is this true?** (`noul`)         | Is this bank line already recorded?           | The probability of yes, from 0 to 1                  |
-| **Which one of these?** (`choice`) | Which Account should receive this payment?    | One of your options, with a confidence from 0 to 1   |
-| **Where on this scale?** (`score`) | How urgently should someone review this line? | A position on your levels, with a confidence         |
-
-Confidence is high when the model's probability concentrates on one answer. For _Is this true?_, the probability itself is the signal. Ask several questions about the same facts in one request; the model answers each one independently.
-
-## Design a decision workflow
-
-1. **Find the judgment.**
-
-    Look for the step where a person glances and decides: which Account, is this a duplicate, does this need a second look. A good question is a snap judgment that a knowledgeable person makes in seconds.
-
-2. **Let code gather the facts.**
-
-    Code fetches the item and the context a person would need, such as nearby Transactions, how an Account is usually described, or Book and Account properties. Pass them as named fields, such as `bank_line` and `existing_transaction`. Facts can also be images, such as a receipt photo. Convert PDFs and other files to text or images first.
-
-3. **Ask narrow questions.**
-
-    Ask one judgment per question. Split bigger judgments into several questions and combine the answers in code. Write each question in full: the model sees your instructions and the facts, never the name your code gives the question.
-
-4. **Keep calculation in code.**
-
-    Match amounts, compute date windows, and check balances in code, then ask the model only the part that needs judgment. For example, find Transactions with the same amount inside a date window, then ask only whether their descriptions describe the same movement.
-
-5. **Set thresholds by risk.**
-
-    Decide how sure the model must be before code acts. A missed suggestion costs a person a few seconds; a duplicate posting misstates a Book. Keep thresholds in one reviewable place.
-
-6. **Act when confident; send the rest to a person.**
-
-    Code acts on answers above the threshold and routes the rest to review. This is TypeSafe's [confidence-gated routing](https://docs.typesafe.ai/patterns/confidence-routing) pattern.
-
-7. **Keep Book writes in code.**
-
-    An answer is a judgment, not permission to change a Book. When code posts, it records a normal Transaction, so the Book stays zero-sum whatever the model answered. Store the model revision and the confidence as Transaction properties for the audit trail.
-
-8. **Measure and adjust.**
-
-    Start with conservative thresholds and test them against your own records. Re-check them when the model's revision changes.
-
-## Putting it all together
-
-A bank line arrives: `AMAZON MKTPL*2K4LM`, 89.90 out of Checking. Code finds a manual entry from the day before with the same amount, "Printer toner, Amazon order 114-2K4LM", and asks three questions at once. Jev answered:
-
-| Question                                                                                                  | Answer                         |
-| --------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| Which Account should receive the money? Cloud Hosting, Software Subscriptions, Office Supplies, or Travel | Office Supplies, confidence 1  |
-| Does the existing entry already record this movement?                                                    | Yes, with probability 0.89     |
-| How urgently should a bookkeeper review it? Routine, Check, or Urgent                                     | 0.09, Routine; confidence 0.86 |
-
-Code then decides:
-
-```ts
-// Keep questions and thresholds in one reviewable place.
-const DUPLICATE_THRESHOLD = 0.8;
-const REVIEW_SCORE_THRESHOLD = 1.5;
-const AUTO_POST_CONFIDENCE = 0.9;
-
-interface BankLineAnswers {
-    account: { type: 'choice'; choice: string; confidence: number };
-    already_recorded: { type: 'noul'; noul: number };
-    review_priority: { type: 'score'; score: number; confidence: number };
-}
-
-type BankLineDecision =
-    | { action: 'check-duplicate' }
-    | { action: 'review'; suggestedAccount: string }
-    | { action: 'post'; toAccount: string; confidence: number };
-
-export function decideBankLine(answers: BankLineAnswers): BankLineDecision {
-    if (answers.already_recorded.noul >= DUPLICATE_THRESHOLD) {
-        return { action: 'check-duplicate' };
-    }
-    if (
-        answers.review_priority.score >= REVIEW_SCORE_THRESHOLD ||
-        answers.account.confidence < AUTO_POST_CONFIDENCE
-    ) {
-        return { action: 'review', suggestedAccount: answers.account.choice };
-    }
-    return {
-        action: 'post',
-        toAccount: answers.account.choice,
-        confidence: answers.account.confidence,
-    };
-}
-```
-
-These answers return `check-duplicate`: the movement is probably already recorded, so code posts nothing. When code does post, it records a Transaction from Checking to the chosen Account. The risks to control are a wrong Account and a duplicate movement, which is why those checks come first.
-
-The exact request and response are in the [AI Gateway API guide](https://bkper.com/docs/api/ai-gateway.md#decision-models).
-
-### Context changes confidence
-
-Ask about the same bank line without the manual entry, and the answer changes:
-
-| Facts given                         | Which Account?                                                        |
-| ----------------------------------- | --------------------------------------------------------------------- |
-| The bank line and the manual entry  | Office Supplies, confidence 1                                         |
-| The bank line alone                 | Office Supplies, confidence 0.75, with 0.14 on Software Subscriptions |
-
-The top option is the same, but the model reports that it is less sure, so `decideBankLine` sends the line to review. Give the model the context a person would need.
-
-For more designs, see TypeSafe's [Patterns](https://docs.typesafe.ai/patterns) and [Cookbooks](https://docs.typesafe.ai/cookbooks).
-
-## Common mistakes
-
-- **Asking for analysis.** Ask one snap judgment per question and combine the answers in code.
-- **Asking the model to calculate.** Match amounts, compute date windows, and check balances in code.
-- **Putting the question in its name.** The model never sees question IDs. Write the full question in its instructions.
-- **Treating answers as verdicts.** A probability of yes is not a boolean, and a score can fall between levels. Compare both with thresholds.
-- **Expecting an explanation.** Decision models return no text. Use a [language model](https://bkper.com/docs/ai/models.md) when you need one.
-- **Sending a language-model request.** A decision request carries only the model, the facts, and the questions. See the [request rules](https://bkper.com/docs/api/ai-gateway.md#decision-request).
-
-## Jev by TypeSafe
-
-[Jev](https://docs.typesafe.ai/introduction) is TypeSafe's flagship model and the first System One model. Its Bkper model ID is `jev`.
-
-- **Versions.** `jev-latest` and versioned IDs are accepted but always select the current Jev; you cannot pin a version. Log the revision each answer reports, and re-check tuned thresholds when it changes.
-- **Input.** Text and images. English is Jev's primary training language; other languages work with lower accuracy.
-- **Images.** An experimental TypeSafe feature, so accuracy and limits can change. Send PNG or JPEG images between 280 and 1568 pixels per side as base64 `assets` in a JSON request; TypeSafe's SDKs upload images in a form Bkper AI does not accept. Image tokens count as input. See TypeSafe's [Images](https://docs.typesafe.ai/images) guide.
-- **Known weak spots.** Literal reading, arithmetic, date comparison, and large states full of irrelevant detail. See [Jev 1.13 jaggedness](https://docs.typesafe.ai/model-jaggedness/jev-1.13).
-
-Requests count against your Bkper AI allowance at Jev's [usage rates](https://bkper.com/docs/ai/models.md#usage-rates).
-
-## Build it
-
-- [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai.md#ask-a-decision-model) — ask a decision model from an app Worker, a script, or a browser with TypeSafe's SDK.
-- [AI Gateway API: decision models](https://bkper.com/docs/api/ai-gateway.md#decision-models) — the request, answer guarantees, errors, caching, and compatibility with TypeSafe.
-- [`createDecision` reference](https://bkper.com/docs/api/ai-gateway/operations/createdecision.md) — every field.
-- [Models and Usage](https://bkper.com/docs/ai/models.md) — usage rates, the allowance, and privacy.
-- Building with a coding agent? Point it to this page for design, and to `https://bkper.com/docs/api/ai-gateway.md` for the endpoint, authentication, and errors. TypeSafe's [agent skill](https://docs.typesafe.ai/agent-skill) adds questions and patterns.
-- TypeSafe: [System One](https://docs.typesafe.ai/concepts/system-one), [How to build with System One](https://docs.typesafe.ai/concepts/how-to-build-with-system-one), [AI primer](https://docs.typesafe.ai/introduction/machine-learning-primer), [Primitives](https://docs.typesafe.ai/primitives), [State](https://docs.typesafe.ai/concepts/state), [Confidence](https://docs.typesafe.ai/confidence), and [Patterns](https://docs.typesafe.ai/patterns).
-- [Back to AI overview](https://bkper.com/docs/ai.md).