esoul-sdk 0.24.0 → 0.25.2

package/llms-full.txt

@@ -20,7 +20,11 @@ platform's implementations.
 - [Getting started](docs/01-getting-started.md)
 - [Manifest reference](docs/02-manifest.md)
 - [Documentation index](#documentation)
+- [A service on your computer, connected to your app](docs/20-a-service-on-your-computer.md)
+- [CHANGELOG.md](CHANGELOG.md) — what each version added
+- `api-reference.md` — every export with its signature and doc comment
 - `llms.txt` and `llms-full.txt` — the documentation in one file, for coding models
+- The package on npm: <https://www.npmjs.com/package/esoul-sdk>
 
 ## Features
 
@@ -84,7 +88,8 @@ test helpers. Functions that need the platform (`pluginDb`, `viewerProfile`, `mi
 throw `host only` when called outside it; they are exercised through the test harness or in a
 Forge workbench.
 
-Requirements: Node.js 20 or newer, TypeScript 5, React 19 for the UI entry point.
+Requirements: Node.js 20 or newer (22 for `esoul-device` on a computer), TypeScript 5, React 18 or
+newer for the UI entry point.
 
 ## Concepts
 
@@ -124,11 +129,13 @@ application that provides the named contract.
 | Import | Contents |
 |---|---|
 | `esoul-sdk` | Schema and event types, `defineOps`, `handleOp`, `opTool`, `definePluginChannel`, `defineBindingEvent`, `checkBinding`, `resolveAppRole`, `chartSvg`, `incompleteStateNotice`, `deterministicReducerId`, `callPluginOp`, `kickPluginTask`, `pluginRouteUrl`, `nanoid`, the manifest schema, `compileEnvelope`, `compileCustomRole` |
-| `esoul-sdk/server` | `pluginDb`, `viewerProfile`, `sseStream`, `mintRouteToken`, `readAppState`, `callWorkspaceTool`, `computer`, `emitPluginAppEvent`, `generateAppImage`, `renderChartImage`, `setAppRole`, `listAppRoles`, `defineAppRole`, `removeAppRole`, `getPluginConnectionCredentials`, `pluginFiles`, and the context types (`PluginOpContext`, `PluginRouteContext`, `PluginViewer`, `PluginServerModule`) |
-| `esoul-sdk/react` | `useViewer`, `useSignInWall`, `useAppCanEdit`, `usePluginEventDispatch`, `usePluginRealtime`, `useWorkspaceTools`, `usePluginWorkspaceFiles`, `usePluginFileUpload`, `useFileSources`, `useFileSourceEntries`; the types `PluginViewerPublic`, `SignInWall` |
-| `esoul-sdk/testing` | `memoryDb`, `fakeViewer`, `runOp`, `fakeApps`, `capture`, `startMockOAuth` |
+| `esoul-sdk/server` | `pluginDb`, `viewerProfile`, `sseStream`, `mintRouteToken`, `readAppState`, `callWorkspaceTool`, `computer`, `devices`, `questions`, `credentials`, `llm`, `filesForOp`, `pluginFiles`, `emitPluginAppEvent`, `generateAppImage`, `renderChartImage`, `setAppRole`, `listAppRoles`, `defineAppRole`, `removeAppRole`, `getPluginConnectionCredentials`, and the context types (`PluginOpContext`, `PluginRouteContext`, `PluginViewer`, `PluginServerModule`) |
+| `esoul-sdk/react` | `useViewer`, `useSignInWall`, `useAppCanEdit`, `usePluginEventDispatch`, `runOptimistic`, `useAppNav`, `usePluginRealtime`, `useWorkspaceTools`, `useRemoteReconcile`, `useCredential`, `<ConnectAccount/>`, `<ConnectComputer/>`, `useDevices`, `useDeviceRun`, `useDeviceActions`, the file hooks (`useFileSources`, `useFileSourceEntries`, `useFolderAutocomplete`, `useFileUrls`, `useTransfer`, `usePluginWorkspaceFiles`, `usePluginFileUpload`), `ImageLabeler`; the types `PluginViewerPublic`, `SignInWall` |
+| `esoul-sdk/machine` | what runs ON the person's computer: the `Program` type for a device program (types only), and the `esoul-device` runtime |
+| `esoul-sdk/testing` | `memoryDb`, `fakeViewer`, `runOp`, `fakeApps`, `capture`, `memoryFiles`, `scriptedModel`, `simGmail`, `fakeCredentials`, `startMockOAuth`, `listFailedRequests` |
 | `esoul-sdk/schemas/plugin.schema.json` | The JSON Schema of the manifest |
 | `esoul-app validate <dir>` | Command-line validator for a package folder |
+| `esoul-device` | The runtime on a person's computer: `connect`, `status`, `sh`, `config set`, `disconnect`, `uninstall` (docs/18) |
 
 ## Getting started
 
@@ -502,7 +509,8 @@ Platform columns on every table: `id`, `workspaceId`, `nodeId`, `ownerId`, `crea
 | `setAppRole(ctx, { email, role, attrs? })` | The owner gives an account one of the application's role words, or a composed role, with attribute values (`{ customer: "204" }`) validated against `roles.attributes`. Recorded as an event. |
 | `listAppRoles(ctx)` | `{ people, roles, custom, envelope }`. |
 | `defineAppRole(ctx, definition)`, `removeAppRole(ctx, name)` | The owner composes or removes a role inside `roles.custom`. |
-| `getPluginConnectionCredentials(ctx)` | The credentials of the instance's bound connection. |
+| `credentials(ctx).slot(name)` | The person's account for a declared slot — Google, any OAuth 2.0 provider (Microsoft, Dropbox…) or a pasted API key: `status()` and `fetch(url, init?)`, with the token or key added by the platform and sent only where the slot may reach. Your code never holds it (docs/08). |
+| `getPluginConnectionCredentials(connectionId, pluginId)` | Older: the token of one of the app's own `connections`, readable only from the app's own running call for the workspace owner's connection. Prefer a `credentials` slot (docs/08 §9). |
 | `pluginFiles(ctx)`, `filesForOp(ctx)` | Workspace files and file sources from server code: read by ref or address (`"workspace:/Mail/a.pdf"`), `save` to a path, and `transfer` a list of files into a folder with platform progress, Stop and a clean Retry (docs/09). |
 
 ### `esoul-sdk/react`
@@ -527,6 +535,7 @@ Platform columns on every table: `id`, `workspaceId`, `nodeId`, `ownerId`, `crea
 | `runOp(server, opName, { viewer, args?, db?, apps?, notifyFails? })` | Calls `pluginServer.ops[opName]` with a platform-shaped context. Returns `{ result, notified, emitted }`; throws the op's refusals. |
 | `fakeApps(fixtures)` | Bound applications for `ctx.apps`. |
 | `capture()` | A recorder for callbacks. |
+| `fakeCredentials(slots)` | A stand-in for `credentials(ctx)`: each slot answers as the test says (`status`, `hosts`, `fetch`), the platform's refusals apply, and `calls` records every request (docs/08 §7). |
 | `startMockOAuth(opts?)` | A local OAuth server for connection tests. |
 
 ### Command line
@@ -569,7 +578,7 @@ Exits 0 when the folder is a well-formed application package; otherwise prints e
 | [5. The UI](docs/05-ui.md) | React, hooks, theme, responsive rules |
 | [6. The server](docs/06-server.md) | Ops, routes, webhooks, `computer`, charts, calling other applications |
 | [7. Background tasks](docs/07-background-tasks.md) | The durable executor, the replay model, concurrency |
-| [8. Connections](docs/08-connections.md) | OAuth and API-key connections held by the platform |
+| [8. Accounts](docs/08-connections.md) | The person's Google, Microsoft or any OAuth 2.0 / API-key account, used through the platform without your code holding the token |
 | [9. Files](docs/09-files.md) | Workspace files, Drive, file providers |
 | [10. Testing](docs/10-testing.md) | The fold contract, ops, tasks and rules as tests |
 | [11. Shipping](docs/11-shipping.md) | The repository, review, release, install, dependencies |
@@ -578,12 +587,20 @@ Exits 0 when the folder is a well-formed application package; otherwise prints e
 | [14. Your own tables](docs/14-database.md) | `db`, rules, scopes, sealed fields, indexes, migrations |
 | [15. Realtime](docs/15-realtime.md) | Topics, audiences, addressing |
 | [16. Bindings](docs/16-bindings.md) | Slots, contracts, reaching another application |
+| [17. Editing and merging](docs/17-editing-and-merging.md) | An editor that takes changes from other devices and agents; merges |
+| [18. Your computer](docs/18-your-computer.md) | The device arm: commands, the workspace, programs, `esoul-device` |
 | [19. Model calls](docs/19-model-calls.md) | `llm(ctx)`: billed model calls, budgets, `scriptedModel()` for tests |
+| [20. A service on your computer](docs/20-a-service-on-your-computer.md) | A walk-through: a program that keeps a service running on the person's computer, talking to the app both ways — built in the Forge, then installed |
 
 ## Versions
 
+From 0.20.0 on, every version is in [CHANGELOG.md](CHANGELOG.md) (accounts through the platform — Google, then any OAuth 2.0 or API-key provider in 0.25.0,
+model calls, file transfers, opened-from-outside navigation, server-only events, the questions bell,
+mail waits). Earlier:
+
 | Version | Changes |
 |---|---|
+| 0.16.0 – 0.19.1 | `runOptimistic` and the failed-request banner; stable list paging; editor sync (`useRemoteReconcile`, `mergeLines` / `mergeFields` / `mergeRecordsById`); the device arm — `devices(ctx)`, `<ConnectComputer/>`, the `esoul-device` runtime, declared commands, the shared command line, an app's own program on the computer (docs/17, 18). |
 | 0.15.0 | **Files work in a Forge box**, and do more: `FilesApi.list(…, opts)` narrowed at the source, `listAll`, `resolvePath`, `readMany`, `write` (make or replace by name — a label file beside its image; manifest `fileSources.write`), `readGrant` + `fileGrantUrl` (signed, expiring URLs for an `<img>` in a preview and for a machine). UI: `useFolderAutocomplete`, `useFileUrls`, `useFileSourceEntries(…, opts)` with `loadMore`, `listFileEntries`, `resolveFilePath`. `ImageLabeler` / `PolygonCanvas` — the Explorer's polygon editor as a component. Pure: `pairImagesWithLabels`, `serializeLabelMe`, `parseLabelMe`, `labelFileNameFor`. Testing: `memoryFiles`. |
 | 0.14.0 | Attribute-scoped access: `roles.attributes` (typed; validated when granted; `viewer.attrs`); scoped rule principals `{ role, where }` with `viewer.<attribute>`, applied to reads, aggregates, updates and deletes and filling or refusing creates, in both database clients; a rule combining `creator` with a scoped role is refused. `compileManifestRules` is the one reader of a manifest's rules. VIEW AS personas carry attributes (`visitor-a?customer=204`). |
 | 0.13.0 | Composed roles: `roles.custom` envelope; `defineAppRole`, `removeAppRole`; `setAppRole` with attributes; `listAppRoles` returns composed roles and the envelope. Reads, updates and deletes are narrowed by the composition in both database clients; surfaces not handed to the role are refused; `useViewer().customRole` and `can`. `access: [<roles>]` on a surface. Composed roles are personas in the Forge. |
@@ -771,14 +788,22 @@ schema is shipped at `schemas/plugin.schema.json`.
 | `entry` | the schema module without extension (`app`) |
 | `icon` | a lucide-react name from the curated set (the workbench lists them when yours is wrong); missing → the generic glyph, never a broken tile |
 | `author` | stamped by the workbench at scaffold: `url` is `esoul:user:<id>`, and it is what the release script and the id-collision check read. No email — a manifest may become public |
-| `ops` | server operations exported by `server.ts` (docs/06) |
+| `ops` | server operations exported by `server.ts` (docs/06). A list of names (each `write`), or an object `name → { "access": "read" \| "public" \| "write" \| "roles", "roles"?, "requires"?: "account" }` (docs/13) |
+| `routes` | HTTP routes `/api/plugins/<id>/route/<name>` served by `server.ts`, same object form; `"access": "token"` makes a door for a machine (`mintRouteToken`, docs/06) |
 | `webhooks` | inbound routes `POST /api/plugins/<id>/webhook/<hook>` served by `server.ts` (docs/06) |
-| `kickableTasks` | task names the **browser** may kick (docs/07) |
+| `kickableTasks` | task names the **browser** may kick (docs/07); list or the object form |
 | `pollTasks` | tasks the platform kicks on a cadence, 5-minute granularity, minimum 5 (docs/07) |
+| `roles.vocabulary` / `roles.default` | your app's own words for people (`["staff", "customer"]`) and which word each platform role starts as (docs/13) |
 | `roles.attributes` | what a grant may say about a person, typed: `{ "customer": "int" }` — rules scope a role by `viewer.<attribute>` (docs/13) |
 | `roles.custom` | the envelope an OWNER composes roles inside at runtime — fields a role may be scoped by / denied / change, transitions, surfaces, attributes (docs/13) |
 | `workspaceTools` | the grant wall for calling OTHER apps' tools — `<applicationType>:<tool base name>`; absent = no cross-app access (docs/04, 06) |
-| `connections` | OAuth2 / API-key connections the user grants once and the platform holds sealed; **names of env vars, never values**, and only the app's own: `PLUGIN_<ID>__<NAME>`; endpoints https (docs/08) |
+| `db` | your own tables: fields, indexes, per-row `rules`, `sealed` fields — generated and scoped by the platform, additive on update (docs/14) |
+| `channel` | realtime topics and who hears each (audiences) (docs/15) |
+| `uses` / `provides` | binding slots another app fills by contract, and the contracts you provide (docs/16) |
+| `credentials` | the person's accounts the app uses, one slot for now: `family: "google"` (`scopes`), `"oauth2"` (any OAuth 2.0 provider — `provider: { name, authorizeUrl, tokenUrl, scopes, hosts }`) or `"apiKey"` (`provider: { name, hosts, header?, prefix? }`), plus `why`, `label?`, `background?`. The person connects once in Account settings and assigns the account; your code calls through `credentials(ctx).slot(name).fetch` and never sees the token, key or client secret (docs/08) |
+| `llm` | model calls billed to the owner: tiers, `dailyBudgetUsd`, `why`; called with `llm(ctx)` / `ctx.llm` — never a model SDK (docs/19) |
+| `device` | parts that run on the person's computers: `commands`, `program` (`main`, `resident`, `setup`, `selfTest`), `config`, `redact`, `onAppDeleted` (docs/18, 20) |
+| `connections` | older: OAuth2 / API-key connections whose token your code reads itself (`getPluginConnectionCredentials`); prefer a `credentials` slot. **Names of env vars, never values**, and only the app's own: `PLUGIN_<ID>__<NAME>`; endpoints https (docs/08 §9) |
 | `fileSources` / `fileProviders` | consent to read workspace files and providers; providers you contribute (docs/09) |
 | `fileProducers` | `[{ key, label }]` — your app's own bytes as a file-transfer source; implemented by `pluginServer.fileProducers[key]` (docs/09) |
 | `platformApi` | refuse install outside `[min, max]` of the platform contract version |
@@ -1031,6 +1056,12 @@ execute: async (args) => {
 }
 ```
 
+Wait for **one of**: `threadId` (the next message on that thread), or `fromEmail` (the next message
+from that sender, optionally with exactly that `subject`). `timeoutSeconds` defaults to 7 days
+(60 s – 30 days); `onResume` / `onTimeout` replace the lines the run reads when it wakes
+(`{{messageId}}`, `{{from}}`, `{{subject}}`, `{{threadId}}` are filled in). The wake is scoped to
+this workspace and this inbox, and never to the account's own sends.
+
 The run wakes on `workspace/email.message_arrived` for this inbox (the platform sends it for the
 Gmail app's live mail) and first checks the inbox's folded `messages` for an arrival newer than
 `afterTimestamp`, so a reply that landed before the wait is not missed.
@@ -1294,6 +1325,31 @@ inline SVG pattern and the thing's icon reads as "not photographed yet"; a grey
 rectangle reads as broken. Fix the aspect ratio in both branches and nothing
 moves when a photograph arrives.
 
+## Images, films and fonts the app ships with — assets
+
+An app's package holds text only. Its media is an **asset**: the bytes go to a content-addressed
+store the platform runs, the package carries `assets.json` (written FOR you), and the app renders
+one immutable URL that is the same in a Forge preview, installed, and on a custom domain.
+
+Put one with the board's `put_app_asset {pluginId, name, fileId | contentBase64 | sourceUrl}` (a
+workspace file — what `generate_image` / `generate_video` made —, a public https URL ≤ 64 MB, or
+≤ 3 MB of base64 a model wrote itself), or over the local `esoul-mcp` with `forge_put_asset(...,
+file=…)` for a file on the person's disk (≤ 64 MB). Names: `webp png jpg jpeg gif avif svg mp4 webm
+mp3 m4a woff2 woff pdf json` — never a script or a page.
+
+```tsx
+import assets from "./assets.json";
+import { assetUrl, assetUrlOrNull } from "esoul-sdk";
+
+<video src={assetUrl(assets, "hero.mp4")} poster={assetUrl(assets, "hero.jpg")} playsInline muted loop />
+<img src={assetUrl(assets, "logo.webp")} alt="" />
+const maybe = assetUrlOrNull(assets, "intro.mp4");   // null when the asset is not there
+```
+
+`assetUrl` never throws: a name missing from `assets.json` logs once and returns an address that
+404s, so the page stays up. The same bytes twice are one object; `remove_app_asset` takes a name
+out. URLs are `/pa/<pluginId>/<sha256>.<ext>`, served immutable.
+
 
 
 ==============================================================================
@@ -1357,8 +1413,21 @@ folds to one item. Fail CLOSED when no secret is configured.
 ## `readAppState(nodeId)`
 
 One app, folded to head: `{ nodeId, workspaceId, applicationType, foldedSeq, state }`, or `null`
-when absent. Use it for your own instance and, with care, for other apps in the same workspace.
-Never a raw database read — the import wall refuses `prisma` and the state column lags the log.
+when absent. Never a raw database read — the import wall refuses `prisma` and the state column lags
+the log.
+
+It reads for the call the platform is running, and only what that call may see:
+
+- your own app type in your workspace — always;
+- another app type in your workspace — only when your manifest grants one of its tools in
+  `workspaceTools` (`"spreadsheet:add_row"` lets you read spreadsheets); otherwise it is refused,
+  naming the line to add;
+- an app in another workspace — `null`, the same answer as an app that does not exist;
+- from a webhook (which runs for no instance) — only your own type, in any workspace, to find the
+  instance to route to;
+- outside an op, route, task or webhook — it throws.
+
+A Forge box applies the same rule.
 
 ## Asking the person — `questions(ctx)`
 
@@ -1397,9 +1466,12 @@ const r = await callWorkspaceTool({
 ```
 
 Gated exactly like the UI: the manifest must declare `"my_computer:claude_task"` in
-`workspaceTools`, and the target must live in the calling app's own workspace. Name a specific
+`workspaceTools`, and the target must live in the calling app's own workspace. `pluginId` and
+`nodeId` must be the running call's OWN app instance — any other pair is refused. Name a specific
 instance with `targetNodeId` instead of `appType`. For a `my_computer`, prefer `computer(ctx, nodeId)`
-below, which parses the answers and knows the waits. This is how an app runs a `my_computer`
+below, which parses the answers and knows the waits. (For a part of YOUR app that runs on the
+person's computer — a service, a program, declared commands — use the device arm instead:
+[18](18-your-computer.md), [20](20-a-service-on-your-computer.md).) This is how an app runs a `my_computer`
 (commands, Claude Code sessions, results), fills a spreadsheet from a job, or books a calendar.
 
 ## `computer(ctx, machineNodeId)` — a paired machine, from server code
@@ -1510,10 +1582,14 @@ Emit ANOTHER app's own events (its `dataCreator` shape) into the same workspace,
 your plugin — for mirroring into a native app whose processors you cannot call directly.
 Same-workspace only.
 
-## Connections in server code
+## Accounts in server code
 
-`ctx.cloudConnectionId` is the instance's bound connection; resolve it with
-`getPluginConnectionCredentials(connectionId, pluginId)` (docs/08).
+The person's accounts — Google, Microsoft or any OAuth 2.0 provider, or a pasted API key — are
+reached through `credentials(ctx).slot(name).fetch(url)`: the platform adds the token or key, sends
+it only where the slot may reach, and your code never holds it (docs/08). `ctx.cloudConnectionId`
+is the id of the account assigned to the instance (an id, not a secret). The older
+`getPluginConnectionCredentials(connectionId, pluginId)` reads one of the app's own `connections`
+(docs/08 §9).
 
 ## What server code may import
 
@@ -1593,6 +1669,34 @@ the example stops streaming — nothing durable happened unless the handler wrot
 task (docs/07) survives everything and costs seconds per hop. The stopwatch ships both and
 records which one drove each run; measure before you choose.
 
+## The headless bridge — a browser on the platform, for a page-shaped engine
+
+Some engines exist only as a web page: a WebAssembly CAD kernel, a canvas renderer. The
+person's open tab can run it; `headlessBridge(ctx, …)` runs it on the platform too, so an agent
+with nobody's tab open (a phone with the app closed, an agent network, MCP) gets the same work
+done — no computer of the person's involved.
+
+```ts
+import { headlessBridge } from "esoul-sdk/server";
+
+const r = await headlessBridge(ctx, {
+  url: "https://my-runtime.example/page.html?parent=https%3A%2F%2Fmy-runtime.example",
+  boot: { field: "type", oneOf: ["ready", "error"] },            // the page's own ready message
+  calls: [{ id: "replay", message: { myBridge: 1, id: "replay", method: "replay", args: { … } } }],
+});
+r.boot;            // the ready message
+r.replies[0];      // the first message whose `id` equals "replay"
+r.timings;         // launchMs / bootMs (cold only), per-call ms, totalMs
+r.warm;            // true when the page was already open on the platform
+```
+
+The page is loaded top-level, so it is its own `parent`: a bridge written for an iframe answers
+unchanged when `?parent=` names the page's own origin. The browser and the loaded page stay warm
+on the platform between calls for the same url; the first call pays the launch and the page's
+download, later calls only the calls. `url` must be https and public; at most 32 calls; replies
+up to 24 MB. A Forge box has no browser: there the call throws and says so — keep the app open
+in the preview and let the tab do the work.
+
 
 
 ==============================================================================
@@ -1688,170 +1792,252 @@ Unit-test the handler with a fake `ctx` (`step.run` that just calls the function
 
 
 ==============================================================================
-# 8. Connections and OAuth — tokens the platform holds for you
+# 8. Accounts — the person's logins, used by your app without your app holding them
 
-An app that talks to an outside service declares the connection; the person grants it once in
-Account settings; the platform stores the tokens sealed and refreshes them; your code asks for a
-credential when it needs one. **Secrets never live in your package**: the manifest names
-environment variables, not values.
+An app that works with a person's account at another service (Gmail, Outlook, OneNote, Dropbox,
+Notion, Spotify, GitHub…) declares a **credential slot** in `plugin.json`. The person connects the
+account once, at the user level, in Account settings, and assigns it to the app. Your server code
+calls the service **through the platform**: `credentials(ctx).slot(name).fetch(url)`. The platform
+checks who is calling and where the request goes, then adds the token or key itself.
 
-```json
-"connections": [{
-  "key": "github", "kind": "oauth2", "label": "GitHub",
-  "authorizeUrl": "https://github.com/login/oauth/authorize",
-  "tokenUrl": "https://github.com/login/oauth/access_token",
-  "oauthScopes": ["repo"],
-  "clientIdEnv": "PLUGIN_MY_APP__GITHUB_CLIENT_ID", "clientSecretEnv": "PLUGIN_MY_APP__GITHUB_CLIENT_SECRET"
-}]
-```
+**The token, the key and the OAuth client secret never reach your code, your package, your logs or
+you, the app's developer.** They are sealed (AES-256-GCM) on the server and sent only to the hosts
+the slot declares, which the person saw before connecting.
 
-**An app names only its own environment variables**: `PLUGIN_<ID>__<NAME>` — the app id upper-cased
-with `-` as `_`, two underscores, then upper-case words joined by single underscores (app `my-app` →
-`PLUGIN_MY_APP__GITHUB_CLIENT_ID`). The platform reads these values and sends them to the URLs your
-manifest names, so any other name is refused at validation, at install and again every time the
-platform would read it: an app that could name `DATABASE_URL` would be sent the platform's database.
-The double underscore gives every name exactly one owner (a single one would give app `shop` the
-names of `shop-demo`); a name ending in `_WEBHOOK_TOKEN` is the platform's webhook secret and is
-refused too. `authorizeUrl` and `tokenUrl` must be https — plain http only to `127.0.0.1` /
-`localhost`, where the mock provider from `esoul-sdk/testing` listens. The operator of the platform
-sets the variables; `pluginEnvPrefix("my-app")` and `pluginEnvNameProblem(id, name)` from `esoul-sdk`
-give the rule in code.
+Three families:
 
-`kind: "apiKey"` instead declares `headerNames` — the header names the app will send; the person
-pastes the key once.
+| `family` | For | The person connects in | The platform enforces |
+|---|---|---|---|
+| `google` | Gmail, Calendar, Contacts, Drive through the platform's verified Google client | Account settings → **Google** | the endpoints your declared Google scopes reach |
+| `oauth2` | any OAuth 2.0 provider: Microsoft (Outlook, OneNote, OneDrive, Teams), Dropbox, Spotify, GitHub, Slack… | Account settings → **Accounts** | the hosts your provider block declares; the provider enforces the scopes |
+| `apiKey` | a key or personal access token the person pastes (Notion, OpenWeather, Airtable…) | Account settings → **Accounts** | the hosts your provider block declares |
 
-## Using a credential
+One account serves every app of the same provider: a person who connects Microsoft once can assign
+that account to an Outlook app and a OneNote app. Each assignment is the person's act, recorded on
+the app's timeline (`workspace/credential_bound`), like Gmail's Google account.
 
-> **Deprecated for Google.** `getPluginConnectionCredentials` hands your code the token itself. For
-> the person's Google account use a platform account slot instead (below): your code never holds
-> the token. It stays for an app's own oauth2/apiKey connections until those move to slots too.
+## 1. Declare the slot
 
-```ts
-import { getPluginConnectionCredentials } from "esoul-sdk/server";
+### `google`
 
-async function listRepos(ctx: PluginOpContext) {
-  if (!ctx.cloudConnectionId) throw new Error("connect GitHub in Account settings first");
-  const cred = await getPluginConnectionCredentials(ctx.cloudConnectionId, "my-app");
-  if (cred.kind !== "oauth2") throw new Error("expected an OAuth connection");
-  const r = await fetch("https://api.github.com/user/repos", { headers: { Authorization: `Bearer ${cred.accessToken}` } });
-  // …
+```json
+"credentials": {
+  "mailbox": {
+    "family": "google",
+    "scopes": ["gmail.modify"],
+    "label": "Mailbox",
+    "why": "Reads, labels and sends mail in the inbox you choose.",
+    "background": true
+  }
 }
 ```
 
-The platform unseals, checks expiry and refreshes with the stored refresh token before handing
-you `accessToken`. Never log it, never put it in an event, never return it from a tool.
+`scopes` are Google's, short (`gmail.modify`) or full
+(`https://www.googleapis.com/auth/gmail.modify`), from: `gmail.readonly`, `gmail.modify`,
+`gmail.send`, `gmail.compose`, `gmail.labels`, `calendar.events`, `calendar.readonly`, `contacts`,
+`contacts.readonly`, `drive.readonly`, `drive.file`. `openid`, `email` and `profile` are implicit.
 
-An instance is **bound** to one connection (`ctx.cloudConnectionId`); a person with two GitHub
-accounts adds two instances. File providers you contribute receive `ctx.connectionId` per active
-connection (docs/09).
+### `oauth2` — any OAuth 2.0 provider
+
+```json
+"credentials": {
+  "microsoft": {
+    "family": "oauth2",
+    "label": "Microsoft account",
+    "why": "Reads and sends mail in your Outlook mailbox.",
+    "background": true,
+    "provider": {
+      "name": "Microsoft",
+      "authorizeUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+      "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+      "scopes": ["offline_access", "User.Read", "Mail.ReadWrite", "Mail.Send"],
+      "hosts": ["graph.microsoft.com"],
+      "accountUrl": "https://graph.microsoft.com/v1.0/me",
+      "accountField": "userPrincipalName",
+      "authorizeParams": { "prompt": "select_account" }
+    }
+  }
+}
+```
 
-## Platform accounts (Google)
+| `provider` field | Meaning |
+|---|---|
+| `name` | The service as the person knows it. Shown on every screen and in every refusal. |
+| `authorizeUrl`, `tokenUrl` | The provider's endpoints (authorization code + PKCE S256). https only (plain http only to `127.0.0.1` / `localhost`, for the mock provider). Accounts are "of the same provider" when both URLs are the same. |
+| `scopes` | The provider's own scope words. Ask for `offline_access` (or the provider's equivalent) so the platform gets a refresh token. |
+| `hosts` | **The only hosts the token is ever sent to**: DNS names, no scheme, port, path or IP address. 1–10. |
+| `accountUrl` + `accountField` | A GET on one of `hosts` that names the account (e.g. Graph's `/me` → `userPrincipalName`). Declare it, or ask for `openid` so the provider's id token names the account: **an account the platform cannot name is refused** (two unnamed accounts would overwrite each other). |
+| `authorizeParams` (optional) | Extra sign-in parameters (`prompt`, `login_hint`…). `client_id`, `redirect_uri`, `scope`, `state` and PKCE are the platform's. |
+| `tokenAuth` (optional) | `"body"` (default: client id and secret in the form) or `"basic"` (HTTP Basic). |
+| `clientIdEnv`, `clientSecretEnv` (optional) | A client **the platform's operator** holds for your app (`PLUGIN_<ID>__…` env vars, the rule in §9). Without them, each person registers their own client once (§2). |
 
-The person connects a Google account once, in **Account settings → Google**, and assigns it to your
-app. Your app declares what it needs in `plugin.json`, and calls Google **through the platform**:
+### `apiKey` — a key the person pastes
 
 ```json
 "credentials": {
-  "mailbox": {
-    "family": "google",
-    "scopes": ["gmail.modify"],
-    "label": "Mailbox",
-    "why": "Reads, labels and sends mail in the inbox you choose.",
-    "background": true
+  "notion": {
+    "family": "apiKey",
+    "why": "Reads the pages you share with the integration.",
+    "provider": {
+      "name": "Notion",
+      "hosts": ["api.notion.com"],
+      "header": "Authorization",
+      "prefix": "Bearer ",
+      "keyHelp": "Notion → Settings → Connections → Develop or manage integrations → Internal integration secret.",
+      "verifyUrl": "https://api.notion.com/v1/users/me"
+    }
   }
 }
 ```
 
+`header` defaults to `Authorization`, `prefix` to `"Bearer "` for that header and `""` for any
+other (`"X-Api-Key"`, say). `verifyUrl`, when declared, is called with the key before it is kept: a
+401/403 refuses it. `Cookie`, `Host`, `Content-Length` and similar headers cannot carry a key.
+
+### Rules for every family
+
 - The slot name is lower-case words joined by `-`. **One slot per app for now**; several are coming.
-- `scopes` are Google's, short (`gmail.modify`) or full
-  (`https://www.googleapis.com/auth/gmail.modify`), from: `gmail.readonly`, `gmail.modify`,
-  `gmail.send`, `gmail.compose`, `gmail.labels`, `calendar.events`, `calendar.readonly`,
-  `contacts`, `contacts.readonly`, `drive.readonly`, `drive.file`. `openid`, `email` and `profile`
-  are implicit.
 - `why` is the sentence the person reads before assigning an account.
-- `background: true` lets the app's own work with nobody present (a scheduled sync) use the
-  account. Without it only the account's owner, acting through the app, can.
-
-### Server: `credentials(ctx).slot(name)`
+- `background: true` lets the app's own work with nobody present (a scheduled sync, a task kicked by
+  the app) use the account. Without it only the account's owner, acting through the app, can.
+- `label` (optional) names the slot on screen.
+
+## 2. How the person connects
+
+**Google**: Account settings → Google → Connect. One consent covers what the platform offers.
+
+**`oauth2`**: Account settings → **Accounts** lists every installed app that asks for an account,
+with the hosts the token will be sent to, the scopes asked, and where the sign-in and the token
+exchange happen. If the platform holds no client for your app, the person registers **their own
+app with the provider once** (Microsoft: an Entra app registration; GitHub: an OAuth app…), gives it
+the redirect URI the screen shows — `https://<the platform's address>/api/account/credentials/callback`
+— and enters its client id and secret. The secret is sealed and never shown again; a second account
+of the same provider reuses it. Then **Connect** → the provider's sign-in → back, connected, and
+assigned to the app chosen in *Assign to*.
+
+**`apiKey`**: the same screen, a key field (with your `keyHelp`), **Save key**.
+
+Later:
+
+- A `connectUrl` never signs anyone in by itself: it opens Account settings → Accounts on your
+  app's slot, where the person sees the hosts and presses **Connect**. (A link that signed in
+  silently would let any page have a person approve hosts they never saw.)
+- An app of the same provider that needs **more scopes** than the account granted gets
+  `needs_consent`; connecting again from its card asks for the union, so the apps already using
+  the account keep working.
+- **Each app gets only its own scopes.** When one account was granted more than an app asks for
+  (OneNote's `Notes.ReadWrite` beside Outlook's `Mail.ReadWrite`), the platform refreshes a token
+  narrowed to the calling slot's scopes for that app's calls — OneNote's code cannot send mail. A
+  provider that will not narrow (or issued no refresh token) gets the call refused with
+  `not_allowed`, never the whole grant.
+- An assignment ends when the account's owner can no longer write the app's workspace (removed
+  from a shared workspace): the app answers `not_bound` until someone assigns another account.
+- An app that sends the token to a **host the account was not connected for** gets
+  `needs_consent` with `missingHosts`; the person approves the host on the Accounts screen
+  ("Use ann@contoso.com and allow teams.microsoft.com").
+- **Disconnect** releases every app (recorded on each app's timeline) and deletes the token or key.
+
+From your app's own screen, `<ConnectAccount/>` / `useCredential().connect()` (§5) does the right
+thing for each state: assigns the person's only fitting account in place, sends them to sign in and
+assign in one trip, or opens Account settings.
+
+## 3. Server: `credentials(ctx).slot(name)`
 
 ```ts
 import { credentials, CredentialUnavailable } from "esoul-sdk/server";
 
-export const listLabels: PluginOpHandler = async (ctx) => {
-  const g = credentials(ctx).slot("mailbox");
-  const s = await g.status();              // { state: "ready", account: { email } } for the owner
-  if (s.state !== "ready") return { ok: false, state: s.state, connectUrl: s.connectUrl };
-  const r = await g.fetch("https://gmail.googleapis.com/gmail/v1/users/me/labels");
-  return await r.json();
+export const inbox: PluginOpHandler = async (ctx) => {
+  const ms = credentials(ctx).slot("microsoft");
+  const s = await ms.status();              // { state: "ready", provider: { name: "Microsoft", … }, account: { email } } for the owner
+  if (s.state !== "ready") return { ok: false, state: s.state, reason: s.reason, connectUrl: s.connectUrl };
+  const r = await ms.fetch("https://graph.microsoft.com/v1.0/me/messages?$top=25&$select=subject,from,receivedDateTime");
+  if (!r.ok) return { ok: false, status: r.status };
+  return { ok: true, messages: (await r.json()).value };
 };
 ```
 
-`fetch(url, init?)` is the standard `fetch`; the platform adds the token. Pass `ctx` itself — the
-context your op, route or task was called with. A copy (`{ ...ctx }`), a context kept from an
-earlier call, or one used after its call finished is refused. In a task, call it inside
-`ctx.step.run(…)` as well as outside; a webhook runs for no app instance, so kick a task for the
-instance and use the account there.
+`fetch(url, init?)` is the standard `fetch`; the platform adds the token (`Authorization: Bearer …`)
+or the key (in its declared header). Pass `ctx` itself — the context your op, route or task was
+called with. A copy (`{ ...ctx }`), a context kept from an earlier call, or one used after its call
+finished is refused. A **task** (in `app.tsx`, which cannot import `esoul-sdk/server`) uses
+`ctx.credentials("microsoft")` — the same slot, for that run — inside `ctx.step.run(…)` as well as
+outside; a webhook runs for no app instance, so kick a task for the instance and use the account
+there.
+
+## 4. The checks
 
 A request goes out only when **every** check passes, in this order:
 
 1. the context is the platform's, for the call running now;
 2. the slot is declared in your manifest;
-3. the URL is `https://`, on a Google API host, with a clean path (no `..`, no encoded `/` or `.`,
-   no credentials or port), and one of the slot's declared scopes reaches that method and path —
-   `gmail.readonly` reaches only `GET`/`HEAD` under `gmail.googleapis.com/gmail/v1/users/me/`,
-   `gmail.send` only `POST …/messages/send`;
-4. an account is assigned to this app instance;
+3. the URL is `https://`, with a clean path (no `..`, no encoded `/` or `.`, no credentials or
+   port, no method-override parameter), and
+   - `google`: on a Google API host, and one of the slot's scopes reaches that method and path
+     (`gmail.readonly` reaches only `GET`/`HEAD` under `gmail.googleapis.com/gmail/v1/users/me/`,
+     `gmail.send` only `POST …/messages/send`);
+   - `oauth2` / `apiKey`: on one of the slot's `hosts`;
+4. an account of this provider is assigned to this app instance, and its owner can still write
+   the instance's workspace;
 5. the caller is the account's owner (or the app's own background work, when the slot says
    `background: true`);
-6. the account has granted every declared scope, and its grant is alive.
+6. the account has granted every declared scope, was connected for every declared host, and its
+   grant is alive;
+7. `oauth2` / `apiKey`: the host is also one the account was connected for, and resolves only to
+   public addresses.
 
-Any `Authorization`, `Cookie`, method-override or `X-Goog-*` header you set is dropped (except
-`X-Goog-Upload-*` on an upload path). Redirects are followed only to an allowed URL on the same
-host. Response bodies are capped at 35 MB.
+Any `Authorization`, `Cookie`, `Host`, hop-by-hop, method-override or key header you set is dropped (for Google also
+`X-Goog-*`, except `X-Goog-Upload-*` on an upload path). Redirects are followed only for GET/HEAD,
+on the same host, to a URL the slot may reach. Response bodies are capped at 35 MB. An `oauth2`
+token about to expire is refreshed first (rotated refresh tokens are kept; the token endpoint's
+redirects are never followed); a 401 is retried once with a fresh token; a refresh the provider
+refuses marks the account for reconnecting. A token is narrowed to the calling slot's scopes when
+the account was granted more (§2).
 
-### Refusals
+## 5. Refusals, status, and the UI
 
 A refused call throws `CredentialUnavailable` with a `code`:
 
 | `code` | Meaning | What to do |
 |---|---|---|
-| `not_bound` | No account is assigned to this app. | The owner assigns one in Account settings → Google. |
-| `needs_consent` | The account has not granted a declared scope. `missingScopes` names them. | Send the owner to `connectUrl`. |
+| `not_bound` | No account of this provider is assigned to this app. | The owner assigns one (Account settings → Google, or → Accounts), or `<ConnectAccount/>`. |
+| `needs_consent` | The account has not granted a declared scope (`missingScopes`), or was not connected for a declared host (`missingHosts`). | Send the owner to `connectUrl` (or the Accounts screen, for hosts). |
 | `reconnect` | The account's grant was revoked or expired. | Send the owner to `connectUrl`. |
-| `not_allowed` | This caller may not use the account, or the URL is outside the declared scopes. | Nothing, for another person; fix the URL, for your code. |
+| `not_allowed` | This caller may not use the account, or the URL is outside what the slot may reach. | Nothing, for another person; fix the URL, for your code. |
 | `not_declared` | The manifest has no slot of that name. | Declare it. |
-| `rate_limited` | Google asked us to slow down. | Retry after `retryAfterMs`. |
-| `provider_unavailable` | Google could not be reached. | Retry later. |
+| `rate_limited` | The provider asked us to slow down. | Retry after `retryAfterMs`. |
+| `provider_unavailable` | The provider could not be reached or refused the platform itself. | Retry later. |
 
 `status()` answers the same questions without throwing:
-`{ state: "ready" | "not_bound" | "needs_consent" | "reconnect" | "not_allowed", account?, missingScopes?, connectUrl?, reason? }`.
-`account` (the email) is present only when the caller owns the account.
-
-### UI: `useCredential` and `<ConnectAccount/>`
+`{ state: "ready" | "not_bound" | "needs_consent" | "reconnect" | "not_allowed", provider?, account?, missingScopes?, missingHosts?, connectUrl?, reason? }`.
+`provider` is `{ name, family }`. `account` (the email or login) is present only when the caller
+owns the account. Every `reason` is a sentence you can show or relay; none contains a secret.
 
 ```tsx
 import { useCredential, ConnectAccount } from "esoul-sdk/react";
 
-const gm = useCredential("mailbox", { nodeId: identifier.nodeId });
-if (gm.state !== "ready") return <ConnectAccount slot="mailbox" nodeId={identifier.nodeId} />;
-return <p>Mail for {gm.account?.email}</p>;
+const ms = useCredential("microsoft", { nodeId: identifier.nodeId });
+if (ms.state !== "ready") return <ConnectAccount slot="microsoft" nodeId={identifier.nodeId} />;
+return <p>Mail for {ms.account?.email}</p>;
 ```
 
 The hook asks the platform the same question `status()` answers, for the person looking at the
-screen, and asks again when the window regains focus. `gm.connect()` opens the platform's Google
-consent for missing permissions or a reconnect, and Account settings → Google to assign an account.
+screen, and asks again when the window regains focus or an account is assigned anywhere.
+`ms.connect()` assigns, signs in, grants or reconnects, whichever the state needs.
+`<ConnectAccount/>` is one line and one button that does it, worded with the provider's name.
 
-### Why there is no token
+## 6. Why there is no token in your code
 
-The platform's Google client is verified for Gmail, Calendar, Contacts and Drive together, and
-the token it holds carries all of it. Google cannot narrow a token to one app's scopes, and your
-server code runs inside the platform's process. So the token stays with the platform: the
-scopes you declare are enforced at the proxy, per request, and a mistake in an app cannot leak
-the person's mail to somewhere it should not go.
+- **Google**: the platform's Google client is verified for Gmail, Calendar, Contacts and Drive
+  together, and its token carries all of it; Google cannot narrow it per app. The scopes you
+  declare are enforced at the proxy, per request.
+- **Everyone else**: your server code runs inside the platform's process, and the person trusts the
+  platform with their login, not every app they install. A token in app code could be logged,
+  stored, or sent anywhere; through the proxy it goes only to the hosts the person approved, and
+  only when the person (or, for `background` slots, the app's own work) is the caller.
 
-### In a Forge box: one simulated Google account
+## 7. In a Forge box, and in tests
 
-A Forge box holds no credential, so it holds a world instead: one simulated Gmail account,
+**`google`: one simulated Google account.** A Forge box holds no credential, so it holds a world instead: one simulated Gmail account,
 `owner@sim.mail.example`, with a seeded mailbox of 300 synthetic messages (`simGmail()` from
 `esoul-sdk/testing`). Every instance's slot is bound to it, so `status()` answers
 `{ state: "ready", account: { email: "owner@sim.mail.example" } }` for the owner and
@@ -1876,6 +2062,141 @@ The world is deterministic (same seed, same mailbox) and survives preview restar
 In the app's own tests (`esoul-box test`) every test file gets a fresh world of the same seed
 and nothing is written. The installed app uses the person's real account and never the sim.
 
+**`oauth2` / `apiKey`: no outside account exists in a box.** `status()` answers
+`{ state: "not_bound", provider, reason }` with the reason "no Microsoft account in the Forge
+preview: connect one to the INSTALLED app…", and `fetch()` refuses with `not_bound` — after
+production's host wall, so a URL the installed app could never reach is refused as `not_allowed`
+here too. Build it in this order:
+
+1. the code that calls the service, tested with `fakeCredentials` from `esoul-sdk/testing`:
+
+   ```ts
+   import { fakeCredentials } from "esoul-sdk/testing";
+
+   const creds = fakeCredentials({
+     microsoft: {
+       hosts: ["graph.microsoft.com"],
+       fetch: (url) => Response.json(url.pathname === "/v1.0/me/messages" ? { value: [{ subject: "Hi" }] } : {}),
+     },
+   });
+   jest.mock("esoul-sdk/server", () => ({ ...jest.requireActual("esoul-sdk/server"), credentials: (ctx: object) => creds.credentials(ctx) }));
+   // … run the op (runOp), then:
+   expect(creds.calls[0]).toMatchObject({ slot: "microsoft", method: "GET", url: "https://graph.microsoft.com/v1.0/me/messages?$top=25" });
+   ```
+
+   It applies the platform's rules (declared slot, https, `hosts`, `Authorization`/`Cookie`
+   dropped, a not-ready `status` thrown as its code) and records every call. A task test sets
+   `ctx.credentials = (slot) => creds.credentials(ctx).slot(slot)`.
+2. the screen's not-connected state, which the box shows as it is;
+3. install the app, then the person connects the account (§2) and the app runs against it.
+
+## 8. Worked example: Outlook and OneNote on one Microsoft account
+
+Two apps, one account. Each declares the same provider (the same `authorizeUrl` and `tokenUrl`) with its own scopes:
+
+```jsonc
+// outlook-lite/plugin.json
+"credentials": { "microsoft": { "family": "oauth2", "why": "Reads and sends your Outlook mail.", "background": true,
+  "provider": { "name": "Microsoft",
+    "authorizeUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    "tokenUrl": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    "scopes": ["offline_access", "User.Read", "Mail.ReadWrite", "Mail.Send"],
+    "hosts": ["graph.microsoft.com"], "accountUrl": "https://graph.microsoft.com/v1.0/me", "accountField": "userPrincipalName" } } }
+
+// onenote-lite/plugin.json — the same provider block, scopes ["offline_access", "User.Read", "Notes.ReadWrite"]
+```
+
+The person, once:
+
+1. **Register an app with Microsoft**: <https://entra.microsoft.com> (or portal.azure.com) →
+   App registrations → New registration. Supported account types: *any organizational directory
+   and personal Microsoft accounts* (that is what `/common/` serves). Redirect URI: platform
+   **Web**, the URI Account settings → Accounts shows.
+2. Certificates & secrets → New client secret → copy its **Value**. (API permissions need no
+   change: Microsoft asks for the scopes at sign-in.)
+3. In ExternalSoul: Account settings → Accounts → *Outlook lite · Microsoft account* → enter the
+   client id (the registration's *Application (client) ID*) and the secret → Connect → sign in.
+4. *OneNote lite* asks for `Notes.ReadWrite` the account has not granted: its **Connect** signs in
+   again for the union (no new client needed), and both apps use the one account.
+
+The apps' code:
+
+```ts
+// outlook-lite/server.ts
+const ms = credentials(ctx).slot("microsoft");
+await ms.fetch("https://graph.microsoft.com/v1.0/me/sendMail", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ message: { subject, body: { contentType: "Text", content: text }, toRecipients: [{ emailAddress: { address: to } }] } }),
+});
+
+// onenote-lite/server.ts
+const pages = await (await credentials(ctx).slot("microsoft").fetch("https://graph.microsoft.com/v1.0/me/onenote/pages?$top=20")).json();
+await credentials(ctx).slot("microsoft").fetch(`https://graph.microsoft.com/v1.0/me/onenote/sections/${sectionId}/pages`, {
+  method: "POST", headers: { "Content-Type": "text/html" },
+  body: `<!DOCTYPE html><html><head><title>${title}</title></head><body>${html}</body></html>`,
+});
+```
+
+Neither app ever sees the token, the refresh token or the client secret.
+
+## 9. The app's own connections (`connections`) — older, discouraged
+
+Before credential slots, an app declared `connections`: the person connects in Account settings →
+Plugins, and server code reads the token itself with `getPluginConnectionCredentials`. **Use a
+credential slot instead** — with `connections` the token reaches your code, the client must be set
+by the platform's operator, nothing assigns a connection to an app instance, and it does not work in
+a Forge box. It remains for existing apps, restricted: the call must come from your own op, route
+or task, and only connections of the owner of the workspace that call runs in are readable.
+
+```json
+"connections": [{
+  "key": "github", "kind": "oauth2", "label": "GitHub",
+  "authorizeUrl": "https://github.com/login/oauth/authorize",
+  "tokenUrl": "https://github.com/login/oauth/access_token",
+  "oauthScopes": ["repo"],
+  "clientIdEnv": "PLUGIN_MY_APP__GITHUB_CLIENT_ID", "clientSecretEnv": "PLUGIN_MY_APP__GITHUB_CLIENT_SECRET"
+}]
+```
+
+### Environment variables an app may name
+
+**An app names only its own environment variables**: `PLUGIN_<ID>__<NAME>` — the app id upper-cased
+with `-` as `_`, two underscores, then upper-case words joined by single underscores (app `my-app` →
+`PLUGIN_MY_APP__GITHUB_CLIENT_ID`). The platform reads these values and sends them to the URLs your
+manifest names, so any other name is refused at validation, at install and again every time the
+platform would read it: an app that could name `DATABASE_URL` would be sent the platform's database.
+The double underscore gives every name exactly one owner (a single one would give app `shop` the
+names of `shop-demo`); a name ending in `_WEBHOOK_TOKEN` is the platform's webhook secret and is
+refused too. `authorizeUrl` and `tokenUrl` must be https — plain http only to `127.0.0.1` /
+`localhost`, where the mock provider from `esoul-sdk/testing` listens. The operator of the platform
+sets the variables; `pluginEnvPrefix("my-app")` and `pluginEnvNameProblem(id, name)` from `esoul-sdk`
+give the rule in code.
+
+`kind: "apiKey"` instead declares `headerNames` — the header names the app will send; the person
+pastes the key once.
+
+### Reading a connection
+
+The connection's id reaches your code where the platform hands it over: a file provider you
+contribute receives `ctx.connectionId` per active connection (docs/09).
+
+```ts
+import { getPluginConnectionCredentials } from "esoul-sdk/server";
+
+async function listRepos(ctx: { connectionId: string }) {
+  const cred = await getPluginConnectionCredentials(ctx.connectionId, "my-app");
+  if (cred.kind !== "oauth2") throw new Error("expected an OAuth connection");
+  const r = await fetch("https://api.github.com/user/repos", { headers: { Authorization: `Bearer ${cred.accessToken}` } });
+  // …
+}
+```
+
+The platform unseals, checks expiry and refreshes with the stored refresh token before handing
+you `accessToken`. Never log it, never put it in an event, never return it from a tool. Called
+outside your own running op, route or task, or for a connection of anyone but the owner of the
+workspace your call runs in, it throws.
+
 
 
 ==============================================================================
@@ -2170,6 +2491,35 @@ it("the description never claims an emptiness it could not read", () => {
 A UI test renders once with a fixed state and checks the visible chrome and the empty state.
 Keep suites fast; they run beside the live preview on the same machine.
 
+## The testing kit — `esoul-sdk/testing`
+
+Worlds your tests run in, so nothing real is touched and every run is the same:
+
+| Helper | Gives you | Chapter |
+|---|---|---|
+| `memoryDb(manifest)` + `fakeViewer(kind, opts)` | your declared tables in memory, with your REAL row rules compiled; a viewer of any kind (`owner`, `member`, `visitor`, `anonymous`, `agent`, roles and attributes) | 14 |
+| `runOp(pluginServer, "op", { viewer, args, db, apps })` | calls one op with a real-shaped `ctx`; returns its result plus what it `emit`ted and `notify`d | 14 |
+| `fakeApps({ slot: { tools } })`, `capture()` | bound apps for `ctx.apps.<slot>` (calls recorded); a recorder for any callback | 16 |
+| `memoryFiles(tree)` | the files door (`filesForOp`) over an in-memory tree: sources, list, read, write, transfers — with `crashAt` / `failItem` to prove a retry leaves no residue | 09 |
+| `scriptedModel(policy)` | `llm(ctx)` answering from your script; `calls` records every request | 19 |
+| `simGmail(opts)` | a Gmail API at the HTTP level (`fetch`, `install()`), with accounts, `deliver(...)`, personas that reply (`addPersona`), a cold-campaign `crowd(n)`, a virtual clock (`advance(ms)`), `faults` (429/5xx/401/network), `snapshot()` / restore; `sent` and `outbox` say what left | 08 |
+| `fakeCredentials(slots)` | `credentials(ctx)` without accounts: per slot a `status`, the `hosts` it may reach and a `fetch` handler; the platform's refusals (undeclared slot, plain http, a host off the list, a slot not ready) and `calls` recording every request | 08 |
+| `startMockOAuth()` | a local OAuth 2 provider for a connection's sign-in and refresh | 08 |
+| `listFailedRequests()`, `subscribeFailedRequests`, `resetFailedRequests` | what `runOptimistic` reverted and named on the banner | 05 |
+
+```ts
+import { memoryDb, fakeViewer, runOp, scriptedModel } from "esoul-sdk/testing";
+import manifest from "./plugin.json";
+import { pluginServer } from "./server";
+
+it("a customer sees only their own orders", async () => {
+  const db = memoryDb(manifest);
+  await runOp(pluginServer, "place-order", { viewer: fakeViewer("visitor", { userId: "a" }), args: { sku: "x" }, db });
+  const b = await runOp(pluginServer, "list-orders", { viewer: fakeViewer("visitor", { userId: "b" }), db });
+  expect(b.result).toEqual({ orders: [] });
+});
+```
+
 ## Tools
 
 Call `execute` with a recording `eventCallback` and assert the events it emitted and the text it
@@ -3276,11 +3626,37 @@ recorded as a conflict. `baseMerge` runs in every fold: keep it pure, exactly li
 - Device view state (which page is open, scroll, selection) belongs in component state or
   `sessionStorage`, never in a shared event another device would follow.
 
+## 4. Declare `resolveConcurrent` for patch-shaped events
+
+`baseMerge` is for events that write one whole value. An event that writes a PATCH — a list of sub-items it
+changed, each with the version it built on — can do better: declare `merge` with `scope` (the sub-item ids),
+and `resolveConcurrent`. The platform calls it only when the patch would land as a conflict (a writer it never
+saw changed one of its sub-items), with the state it lands on; it merges what it can against the bases it
+carries and returns the rewritten event:
+
+```ts
+merge: { item: (_d, ctx) => `${ctx.applicationId}:cad:model`, scope: (d) => d.delta.ops.map(keyOf), describe: (d) => d.label },
+resolveConcurrent: (state, eventData, { theirsSess }) => {
+  const r = resolveEdit(state, eventData);          // pure: three-way per sub-item against the base each op carries
+  if (!r) return null;                              // cannot reason about it → the plain conflict (applied and marked)
+  return r.clashes.length === 0
+    ? { eventData: r.eventData }                    // everything merged: applied, no marker
+    : { eventData: r.eventData, detail: { kind: "cad-edit", clashes: r.clashes, theirsSess } };
+},
+```
+
+What it returns is what the fold applies, on every device and on the server. Keep it pure and symmetric; a
+property test over randomised edit pairs is the cheapest proof.
+
 
 
 ==============================================================================
 # 18 · Parts of your app that run on the person's computer
 
+> Building a service that runs on the computer and talks to your app? Start with the
+> walk-through, [20 · A service on your computer](20-a-service-on-your-computer.md); this page is
+> the reference.
+
 Some apps need the person's own machine: a GPU for training, files that never
 leave a laptop, a tool installed there, a local network. The **device arm**
 lets an app run commands on a computer the owner connects, with the output
@@ -3340,12 +3716,17 @@ The panel lists connected computers (online, last seen, Disconnect) and a
 **Connect a computer** button. It shows one command to paste in a terminal:
 
 ```
-npx -y -p esoul-sdk@0.19.0 esoul-device connect https://externalsoul.com/api/device/m/offers/off_…
+npx -y -p esoul-sdk@0.19.1 esoul-device connect https://externalsoul.com/api/device/m/offers/off_…
 ```
 
 The runtime ships inside `esoul-sdk` (the `esoul-device` command, and
 `esoul-sdk/machine` for code that runs on the computer). It uses only Node
-built-ins, so a computer needs nothing but Node 22.
+built-ins, so a computer needs nothing but Node 22. The version in the command
+is the runtime's own, pinned by the platform (it moves more slowly than the
+package). A computer without Node uses the panel's other line, which brings a
+pinned Node first, without sudo:
+`curl -fsSL https://externalsoul.com/api/device/install | sh -s -- <link>`.
+The link expires in 10 minutes.
 
 The command holds no secret. The computer makes its own key, prints a code
 (`K7Q-4XM`) and the list of commands; the page shows the same code with
@@ -3415,8 +3796,10 @@ const { run, finished } = useDeviceRun({ workspaceId, nodeId, commandId });
 // run.output streams in as the command prints (first 1 MB kept, then run.tail)
 ```
 
-`useDeviceActions({ nodeId })` gives the owner's buttons from the UI (run,
-cancel, disconnect, approve an update) without writing an op.
+`useDeviceActions({ nodeId })` gives the owner's buttons from the UI (`run`,
+`cancel`, `disconnect`, `approveUpdate`, `setWorkspace` for the reach, `sh`,
+and `recent` runs) without writing an op. `useMyComputers()` and
+`<YourComputers/>` list the person's computers across apps.
 
 ## 6. Local settings stay local
 
@@ -3425,7 +3808,7 @@ manifest declares under `device.config` are set on the computer and never sent
 to the platform:
 
 ```
-npx -y -p esoul-sdk@0.19.0 esoul-device config set "My app" HF_TOKEN
+npx -y -p esoul-sdk@0.19.1 esoul-device config set "My app" HF_TOKEN
 ```
 
 The command receives them as environment variables. `redact` patterns are
@@ -3444,9 +3827,12 @@ applied on the computer before any output leaves it.
 
 ## 8. Testing
 
-In a Forge preview, `devices(ctx)` answers with a clear refusal and
-`<ConnectComputer/>` says computers connect to the installed app. Mock
-`esoul-sdk/server` in unit tests, as for any host function.
+Computers connect to INSTALLED apps. In a Forge preview `devices(ctx).list()`
+answers `[]`, every other `devices()` call throws "computers connect to
+INSTALLED apps", `useDevices`/`useDeviceRun` stay empty, `useDeviceActions`
+throws, and `<ConnectComputer/>` says so. Mock `esoul-sdk/server` in unit tests,
+as for any host function, and test a program with a fake `p`
+([20 §5](20-a-service-on-your-computer.md)).
 
 ## 9. The workspace: agents working on the computer
 
@@ -3462,9 +3848,9 @@ dev server open — the owner gives the app a **workspace**:
 Two parties agree. **The computer** sets a ceiling when it connects:
 
 ```
-npx -y -p esoul-sdk@0.19.0 esoul-device connect <link>                    # this folder (the default)
-npx -y -p esoul-sdk@0.19.0 esoul-device connect <link> --folder ~/proj    # another folder
-npx -y -p esoul-sdk@0.19.0 esoul-device connect <link> --scope computer   # allow the whole computer
+npx -y -p esoul-sdk@0.19.1 esoul-device connect <link>                    # this folder (the default)
+npx -y -p esoul-sdk@0.19.1 esoul-device connect <link> --folder ~/proj    # another folder
+npx -y -p esoul-sdk@0.19.1 esoul-device connect <link> --scope computer   # allow the whole computer
 ```
 
 **The owner** grants each app at most that ceiling from the app's page (the
@@ -3601,8 +3987,16 @@ The rules that keep it safe and quiet:
 
 Where each program stands on each computer — installing, each setup step,
 self-test, running, the program's own `p.status` words, why it failed —
-comes back on `devices(ctx).list()` as `programState`, and `<ConnectComputer/>`
-shows it. The reference app is **CPU monitor** (`src/plugins/cpu-monitor`).
+comes back on `devices(ctx).list()` as `programState` (one computer:
+`devices(ctx).program(linkId).state()`), and `<ConnectComputer/>` shows it.
+
+Limits: a message (`send`) and its answer are each at most 1 MB of JSON; a
+topic matches `[a-zA-Z][a-zA-Z0-9_.:-]{0,63}`; a message for an offline
+computer expires (600 s default). `p.op` calls are resent when no answer has
+come in about 4 s (up to 3 tries) — make those ops idempotent and pass
+`{ key }`. `p.workspaceRoot` is null when the whole computer is granted.
+Nothing reaches INTO the computer: there is no tunnel or open port; a program
+reaches its own localhost and calls out. The reference app is **CPU monitor** (`src/plugins/cpu-monitor`).
 
 ### An agent on each computer
 
@@ -3784,3 +4178,298 @@ expect(model.calls).toHaveLength(1);
 In a **Forge box**, `llm(ctx)` and `ctx.llm` refuse what the platform refuses (`not_declared`,
 `not_allowed`, `model_not_allowed`) and answer everything else from `scriptedModel()` — the box
 holds no model key and never spends a token. Credits and the daily budget are not simulated there.
+
+
+
+==============================================================================
+# 20 · A service on your computer, connected to your app
+
+A guide, start to finish: an app built in the Forge that runs its own
+long-lived service on the person's computer — a local model server, a
+sampler, a bridge to a device on the desk, a trainer's supervisor — and
+talks to it both ways. The reference for every piece is
+[18 · Parts of your app that run on the person's computer](18-your-computer.md);
+this page is the path through it.
+
+## The shape
+
+```
+ your app on ExternalSoul                      the person's computer
+ ─────────────────────────                     ─────────────────────────────
+ server.ts  ── devices(ctx).program(linkId)    device/main.ts  (your PROGRAM,
+               .send("ask", data)  ─────────▶    p.on("ask", …)   kept running,
+                                    ◀───────── answer (≤ 1 MB)    sandboxed)
+ ops.ts     ◀── p.op("report", data) ────────   p.every / events      │
+               (the op sees viewer.device)                             ▼
+                                                     your service on localhost
+                                                     (started by the program,
+                                                      installed by setup steps)
+```
+
+- **The program is the service's keeper.** Your app ships a `device/` folder;
+  the person approves it once on their computer; the runtime installs it,
+  runs your setup steps (a Python venv, `npm ci`, a model download), checks it
+  with your self-test, and keeps it running (`"resident": true`), restarting
+  it when it exits.
+- **App → service:** your server code sends a message to the program; the
+  program's handler does the work — usually a `fetch("http://localhost:…")`
+  to the service it started — and returns the answer.
+- **Service → app:** the program calls one of your app's own ops with
+  `p.op(...)`. The op knows it came from that computer (`ctx.viewer.device`).
+- **Nothing reaches INTO the computer.** There is no tunnel and no open port:
+  the computer only calls out. The program can reach its own `localhost` and
+  the internet; your app reaches the program only through `send`.
+
+## 1. Declare the program (`plugin.json`)
+
+```json
+{
+  "ops": ["ask", "report", "computers"],
+  "device": {
+    "program": {
+      "main": "device/main.ts",
+      "resident": true,
+      "setup": [
+        { "id": "venv", "describe": "Python environment", "run": ["python3", "-m", "venv", ".venv"] },
+        {
+          "id": "deps", "describe": "Install the server",
+          "run": [".venv/bin/pip", "install", "-r", "{program}/device/requirements.txt"],
+          "inputs": ["device/requirements.txt"]
+        }
+      ],
+      "selfTest": { "run": [".venv/bin/python", "{program}/device/self_test.py"] }
+    },
+    "config": { "MODEL_DIR": { "describe": "Where the model weights are on this computer" } },
+    "onAppDeleted": "kill"
+  }
+}
+```
+
+- `setup` runs once per step and per change of its `inputs` — an app update
+  that leaves `requirements.txt` alone does not reinstall. Steps are argv, never
+  a shell line; `{program}` is the program's folder. Relative paths (`.venv`)
+  live in the program's data folder, which is kept across versions.
+- `selfTest` must exit 0 before the program counts as ready; make it the
+  thing your service needs (`claude --version`, a GPU check, an import).
+- `config` names values that stay on the computer (`esoul-device config set
+  "<app name>" MODEL_DIR ~/models`); the program reads them as `p.config`.
+
+## 2. Write the program (`device/main.ts`)
+
+```ts
+import type { Program } from "esoul-sdk/machine";      // types only — nothing is installed beside the program
+import { spawn, type ChildProcess } from "node:child_process";
+import { join } from "node:path";
+
+const PORT = 8711;
+let server: ChildProcess | null = null;
+
+async function healthy(): Promise<boolean> {
+  try { return (await fetch(`http://127.0.0.1:${PORT}/health`)).ok; } catch { return false; }
+}
+
+export default {
+  async start(p) {
+    // Start the service: argv, no shell; its output goes to the program's log.
+    server = spawn(join(p.dataDir, ".venv/bin/python"), [join(p.programDir, "device/serve.py"), "--port", String(PORT)], {
+      cwd: p.dataDir,
+      env: { ...process.env, MODEL_DIR: p.config.MODEL_DIR ?? "" },
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+    for (let i = 0; i < 60 && !(await healthy()); i++) await new Promise((r) => setTimeout(r, 1000));
+    p.status((await healthy()) ? "Model server ready" : "Model server did not start", { ready: await healthy() });
+
+    // App → service: the answer of the handler is the answer of send().
+    p.on("ask", async (data) => {
+      const r = await fetch(`http://127.0.0.1:${PORT}/ask`, { method: "POST", body: JSON.stringify(data), headers: { "content-type": "application/json" } });
+      return await r.json();
+    });
+
+    // Long work: answer at once, report when done (the app's op stores it).
+    p.on("job", async (data) => {
+      const { requestId } = data as { requestId: string };
+      void (async () => {
+        const r = await fetch(`http://127.0.0.1:${PORT}/job`, { method: "POST", body: JSON.stringify(data) });
+        await p.op("report", { requestId, result: await r.json() }, { key: requestId });
+      })();
+      return { accepted: true };
+    });
+
+    // Service → app on a clock.
+    p.every(60_000, async () => p.op("report", { kind: "heartbeat", ok: await healthy() }));
+  },
+  async stop() { server?.kill(); },
+} satisfies Program;
+```
+
+What a program may import: Node built-ins (`node:fs`, `node:child_process`, …),
+files of its own `device/` folder, and `esoul-sdk/machine` **types only**. No
+packages — install what the service needs in a setup step. At most 2 MB and
+200 files; download weights and datasets in setup or at start. Node 22.6+
+runs a `.ts` entry directly (no enums, no namespaces).
+
+## 3. Talk to it from the app (`server.ts`)
+
+```ts
+import { devices, type PluginOpContext } from "esoul-sdk/server";
+
+// App → service. linkId names one connected computer (devices(ctx).list()).
+async function ask(ctx: PluginOpContext, args: { linkId: string; prompt: string }) {
+  const r = await devices(ctx).program(args.linkId).send("ask", { prompt: args.prompt }, { waitSeconds: 30 });
+  if (!r.ok) return { ok: false, error: r.error ?? "the computer did not answer" };   // offline, not approved, handler threw
+  return { ok: true, answer: r.result };
+}
+
+// Service → app. Only the program on a computer may report.
+async function report(ctx: PluginOpContext, args: { requestId?: string; result?: unknown; kind?: string }) {
+  const device = ctx.viewer.device;
+  if (!device) throw new Error("report comes from the program on a computer");
+  await ctx.emit("result_reported", { machineId: device.machineId, hostname: device.hostname, ...args });
+  return { ok: true };
+}
+
+// Which computers there are, and where each program stands.
+async function computers(ctx: PluginOpContext) {
+  return (await devices(ctx).list()).map((d) => ({
+    linkId: d.linkId, hostname: d.machine?.hostname, online: d.machine?.online ?? false,
+    program: d.programState?.phase ?? (d.program ? "approved" : "not approved"),
+    status: d.programState?.status?.text ?? null,
+  }));
+}
+```
+
+Rules that matter:
+
+- **`send` waits at most 55 s** (`waitSeconds`; `0` returns at once with the
+  `commandId`). For anything longer, use the job pattern above: answer
+  `accepted`, finish in the background, `p.op` the result.
+- **A message and an answer are each at most 1 MB of JSON.** Topics match
+  `[a-zA-Z][a-zA-Z0-9_.:-]{0,63}`. For files, hand the program a link
+  (`(await filesForOp(ctx)).readGrant(...)` + `fileGrantUrl`) and let it
+  download; for results, store them through ops or save files.
+- **A queued message for an offline computer expires** (600 s by default) —
+  a click on Monday never runs on Thursday.
+- **`p.op` must be quick and idempotent.** The computer resends a call whose
+  answer has not arrived in about 4 s (up to 3 tries). Pass `{ key }` with a
+  stable id and make the op a no-op the second time (store by `requestId`).
+- **Who can do what:** `send`, `run`, `sh` and `cancel` need a caller who may
+  change the workspace (`ctx.viewer.canWrite`). The program's `p.op` calls run
+  as the owner who approved that computer (`viewer.kind === "agent"`,
+  `viewer.device` set) through your app's own op and its own rules.
+
+`devices(ctx).program(linkId).state()` gives that program's state on that
+computer (installing, a setup step, self-test, running, its last `p.status`
+words, why it failed) — the same that `list()` returns as `programState`.
+
+## 4. The page: connect a computer
+
+```tsx
+import { ConnectComputer, useDevices } from "esoul-sdk/react";
+
+export function Computers({ workspaceId, nodeId }: { workspaceId: string; nodeId: string }) {
+  const { devices } = useDevices({ workspaceId, nodeId });   // pick a linkId for ask()
+  return <ConnectComputer workspaceId={workspaceId} nodeId={nodeId} title="Computers" />;
+}
+```
+
+`<ConnectComputer/>` lists the computers (online, last seen, the program's
+progress and words, Disconnect) and a **Connect a computer** button.
+
+## 5. Build it in the Forge — what you can prove before installing
+
+The Forge box runs your app in a preview. **Computers connect to installed
+apps only**: in the box `devices(ctx).list()` answers `[]`, every other
+`devices()` call throws "computers connect to INSTALLED apps", and
+`<ConnectComputer/>` shows a note saying so. Plan the work in that order:
+
+1. **Prove the program without a computer.** It is a plain object with
+   `start(p)`; give it a fake `p` in a test and call its handlers:
+
+   ```ts
+   import program from "../device/main";
+
+   test("ask goes to the local service and comes back", async () => {
+     const handlers: Record<string, (d: unknown) => unknown> = {};
+     const ops: Array<[string, unknown]> = [];
+     const p = {
+       computer: { hostname: "test", platform: "linux", arch: "x64", cpus: 4, memoryGb: 8 },
+       appName: "Model", programDir: __dirname, dataDir: "/tmp/model-test", workspaceRoot: null, config: {},
+       status: () => {}, log: () => {}, every: () => () => {},
+       on: (t: string, h: (d: unknown) => unknown) => { handlers[t] = h; },
+       op: async (name: string, args: unknown) => { ops.push([name, args]); return { ok: true }; },
+     };
+     // stub the service: global.fetch = jest.fn(...) answering /health and /ask
+     await program.start(p as never);
+     expect(await handlers.ask({ prompt: "hi" })).toEqual({ text: "hello" });
+   });
+   ```
+
+2. **Prove the app side** with `esoul-sdk/server` mocked (`devices` returning a
+   fake whose `program().send` answers), and call `report` with a faked
+   `viewer.device` to see the result land in the fold.
+3. **Run the service itself** in the box if it can run there (`run_in_app`:
+   `python3 device/serve.py --port 8711 &` then `curl localhost:8711/health`) —
+   the same code the program will start.
+4. `check_app` packs `device/` and refuses a program over 2 MB / 200 files or
+   one that imports a package.
+
+What only the installed app can prove: the program installed and running on
+a real computer, `send`, `p.op`, the approval card and the reach choice.
+
+## 6. Install, connect, approve
+
+1. `install_app` (the board's tool, or Install on the board). The app is now
+   on the platform.
+2. Open the app, press **Connect a computer**. The panel shows one command to
+   paste in a terminal on that computer:
+
+   ```
+   npx -y -p esoul-sdk@0.19.1 esoul-device connect https://externalsoul.com/api/device/m/offers/off_…
+   ```
+
+   No Node there? The panel's other line installs a pinned Node first, without
+   sudo: `curl -fsSL https://externalsoul.com/api/device/install | sh -s -- <link>`.
+   The link expires in 10 minutes and holds no secret.
+3. The computer prints a code (`K7Q-4XM`); the page shows the same code with
+   **Approve**, the program's size and version, its setup steps and
+   self-test, and **what the app may reach there**: commands only, its
+   folder, or the whole computer (never more than the computer allowed with
+   `--scope` / `--folder` when it connected).
+4. The runtime installs itself as a user service (systemd on Linux, a
+   LaunchAgent on macOS, a plain background service where neither exists),
+   so it comes back after a reboot. Linux and macOS; Windows via WSL2.
+5. The card shows setup progress, then the self-test, then your `p.status`
+   words. Your app's `computers` op (or `list()`) says `running`.
+
+**Updates.** A new version that changes the program (any file, the setup, the
+self-test) has a new digest and waits for **Approve** on the card; until then
+the computer keeps running the version it has. Changing what the app may
+reach there restarts the program under the new reach.
+
+**Where it runs.** Unconfined only with the whole computer granted (needed
+when the service uses the person's own logins, like Claude Code or git).
+Otherwise in an OS sandbox (bubblewrap on Linux, Seatbelt on macOS): it reads
+the system, writes only `p.dataDir` and the granted folder, and its home and
+`/tmp` are private. No sandbox on the computer → refused, never run
+unconfined. The network is not confined either way.
+
+## 7. Other ways in, and when to use them
+
+| You need | Use |
+|---|---|
+| A long-lived service your app owns, two-way | **A program** (this page) |
+| A known tool run with checked parameters (`nvidia-smi`, a training script) | **Declared commands** — `device.commands` + `devices(ctx).run` ([18 §1–4](18-your-computer.md)) |
+| Agents that work IN a project folder (read, edit, patch, run tests, keep a dev server in a terminal) | **The workspace** — `devices(ctx).sh("term new dev npm run dev", { agent })` ([18 §9](18-your-computer.md)) |
+| A process that is not your program pushes data to your app (a script, a device, a CI job) | **A token route** — declare the route `"access": "token"`, mint with `mintRouteToken(ctx, { route, ttlSeconds })`, the process POSTs with `Authorization: Bearer <token>` ([06 · Routes](06-server.md)). Works in the Forge box too (the box's public preview URL). |
+| The person already runs the My Computer app and the work is one-off shell commands | **`computer(ctx, machineNodeId)`** — shell strings the owner approves, output ≤ 8,000 characters ([06](06-server.md)); works in the box through the board's tab |
+
+## 8. When it does not work
+
+| You see | It means |
+|---|---|
+| `send` → `ok: false`, `expired` | the computer was offline for the message's whole life (600 s) |
+| `send` → error "not approved" / no program in `list()` | the person has not approved the program (or its new version) on the card |
+| `programState.phase === "failed"` | a setup step or the self-test failed, or the program exited five times in five minutes — the card shows the last log lines |
+| "refused: no sandbox" on the card | the computer has neither bubblewrap nor Seatbelt; grant the whole computer or install bubblewrap |
+| the same report stored twice | the op is not idempotent — key it by `requestId` (`p.op(..., { key })`) |
+| `send` answers `the answer was larger than 1 MB` | return a summary; put the bulk in a file and send a link or an id |