wizards 0.5.0 → 0.5.1

package/apps/runtime/dist/docs/dev/plugins/runners.md

@@ -1,15 +1,15 @@
 ---
 title: Runners
-description: A door a wizard runs through, beside the page and the chat — a call, a messenger, a kiosk — and the run API that drives runs from it.
-version: 0.4.4
+description: A door a wizard runs through, beside the page and the chat (a call, a messenger, a kiosk), and the run API that drives runs from it.
+version: 0.5.0
 ---
 
 A runner is a way to run a wizard. The runtime has four: the stepped page at `/w/<token>`, the
 chat at `/w/<token>/chat`, live voice at `/w/<token>/talk` and the video call at
-`/w/<token>/video`; the last two only where a speech model is set up. A plugin adds more. The
-owner picks them per wizard when it is made, and later under "Change" in the share dialog; the
-link opens the first page runner that is on, the others answer under their own address or from
-their own channel.
+`/w/<token>/video`. The last two are there only where a speech model is set up. A plugin adds
+more. The owner picks them per wizard when it is made, and later under “Change” in the share
+dialog. The link opens the first page runner that is on; the others answer under their own
+address or from their own channel.
 
 ## Register a runner
 
@@ -32,24 +32,25 @@ server.registerRunner({
 
 | | |
 |---|---|
-| `id` | Lower case, digits and `-`, starting with a letter, at most 24 characters. The sub-path of the wizard's address. Not one of the built-in runners (`steps`, `chat`, `talk`, `video`), `runs` or `icons`: such an id throws "is taken" |
+| `id` | Lower case, digits and `-`, starting with a letter, at most 24 characters. The sub-path of the wizard’s address. Not one of the built-in runners (`steps`, `chat`, `talk`, `video`), `runs` or `icons`: such an id throws “is taken” |
 | `label` | `{ de, en }`: its name in German and English |
 | `kind` | `page`: the person opens an address. `channel`: the runner has an address of its own (a number, a bot) and drives runs from its webhooks |
 | `capabilities` | What the runner takes in and shows; see below |
-| `page` | A page runner's handler: what `/w/<token>/<id>` answers with. Nobody is signed in. A page runner without one throws when it is registered |
-| `problem` | `() => string \| { text, kind?, note?, plan? } \| null`, may be async: why the runner cannot be used in the current tenant right now ("Not connected: Settings → WhatsApp"), asked inside the tenant whenever the studio lists the runners. A text is something to set up: the share dialog's row says "Noch nicht eingerichtet" with "Einrichten". An object says its `kind`: `setup` (the same), `waiting` (asked for, waiting for someone else; the row has no button), `plan` (the tenant's plan does not have it; the row offers the plans, "`plan` ansehen"); `note` (`{ de, en }`) is what the row says instead ("Nummer angefragt", "Ab Pro") |
-| `address` | A channel runner: `(wizard: { id, title, token }) => { number?, keyword?, link? } \| null`, may be async. Where a person reaches that wizard: the number, the keyword that picks it there, and a link that opens the channel with the keyword written (`sms:…`, `https://wa.me/…`). The share dialog shows the keyword and number under the runner's name, copies the link (else the number) and offers the link as a QR code. Asked for each wizard that has the runner on; null while it is not set up |
+| `page` | A page runner’s handler: what `/w/<token>/<id>` answers with. Nobody is signed in. A page runner without one throws when it is registered |
+| `problem` | `() => string \| { text, kind?, note?, plan? } \| null`, may be async: why the runner cannot be used in the current tenant right now (“Not connected: Settings → WhatsApp”). The runtime asks it inside the tenant whenever the studio lists the runners, and a runner with a problem can’t be switched on. A text is something to set up: the share dialog’s row says “Not set up yet” and offers “Set up”. An object says its `kind`: `setup` (the same), `waiting` (asked for and waiting for someone else; the row says “Waiting” and has no button) or `plan` (the tenant’s plan does not have it; the row says “Not in your plan” and offers “See {plan}” with the `plan` it names, else “See the plans”). `note` (`{ de, en }`) is what the row says instead (“Number requested”, “From Pro”) |
+| `address` | A channel runner: `(wizard: { id, title, token }) => { number?, keyword?, link? } \| null`, may be async. Where a person reaches that wizard: the number, the keyword that picks it there, and a link that opens the channel with the keyword written (`sms:…`, `https://wa.me/…`). The share dialog shows the keyword and number under the runner’s name, copies the link (else the number) and offers the link as a QR code. Asked for each wizard that has the runner on; null while it is not set up |
 
-A page runner is served at `/w/<token>/<id>` for every wizard that switched it on. From
-source, where Vite serves the pages, the same handler answers at
-`/api/public/wizards/<token>/runners/<id>`; the public wizard's `runners` list carries the
+A page runner is served at `/w/<token>/<id>` for every wizard that switched it on. When you run
+from source, where Vite serves the pages, the same handler answers at
+`/api/public/wizards/<token>/runners/<id>`; the public wizard’s `runners` list carries the
 right address either way.
 
 ### Capabilities
 
-The runner declares; the runtime works out per wizard how far it gets, and the editor shows it:
-everything in the channel, hands off to the page at these steps, or not possible. A kind the
-runtime does not know throws when the runner is registered.
+The runner declares what it can do. The runtime works out per wizard how far it gets:
+everything in the channel, a hand-off to the run page at some steps, or not possible. Where it is
+not possible, the share dialog’s row says “Not possible:” with the steps. A kind the runtime does
+not know throws when the runner is registered.
 
 | Field | Says |
 |---|---|
@@ -58,12 +59,12 @@ runtime does not know throws when the runner is registered.
 | `output.pictures` | What it shows as a picture with a link to the real thing. Anything else is a link |
 | `asks` | `confirm` for a running step that asks before it changes something; `login` only where a browser types the sign-in |
 | `review` | `accept`, `regenerate`, `edit` |
-| `waits` | Whether it stays through a step that takes minutes. A runner that cannot gets "not possible" for such wizards |
+| `waits` | Whether it stays through a step that takes minutes. A runner that can’t is not possible for such wizards |
 | `handoff` | How a link to the run page reaches the person: `screen`, `thread`, `sms`, `push`. A runner with none cannot hand off |
 
 ## Drive a run
 
-`server.runs` holds the functions behind the MCP tools, for the plugin's own door. A run
+`server.runs` holds the functions behind the MCP tools, for the plugin’s own door. A run
 started here is a live run of the published wizard for a person of that door.
 
 ```ts
@@ -89,17 +90,17 @@ server.registerPublicRoute({
 
 | Call | |
 |---|---|
-| `runs.start({ token \| wizardId, person, answers?, runner? })` | Starts a live run. `person` names who it is for on the door; the runtime keeps a hash of it as the run's visitor, so what the wizard remembers is theirs on the run page too. `answers` fills the first page; what did not fit comes back as `refused`. Gives the run's ticket |
-| `runs.report(runId, { waitSeconds?, draft? })` | The run as it stands: `lang`, `waitingFor` (a page with the fields shown and what they know, a review, a question), outputs with signed links and a `picture` (a PNG of a document, a dashboard or a widget), cost, `browserUrl`. Waits up to 45 seconds while the run works. A door that asks a page one field at a time passes what it has as `draft`: a field's `shown` then follows those answers, as the form on the screen does |
+| `runs.start({ token \| wizardId, person, answers?, runner? })` | Starts a live run. `person` names who it is for on the door; the runtime keeps a hash of it as the run’s visitor, so what the wizard remembers is theirs on the run page too. `answers` fills the first page; what did not fit comes back as `refused`. Gives the run’s ticket |
+| `runs.report(runId, { waitSeconds?, draft? })` | The run as it stands: `lang`, `waitingFor` (a page with the fields shown and what they know, a review, a question), outputs with signed links and a `picture` (a PNG of a document, a dashboard or a widget), cost, `browserUrl`. Waits up to 45 seconds while the run works. A door that asks a page one field at a time passes what it has as `draft`: a field’s `shown` then follows those answers, as the form on the screen does |
 | `runs.wizards(runner)` | The published wizards of the tenant that switched the runner on: what the door offers, with `token`, `title` and `lang` |
 | `runs.answerPage(runId, stepId, values)` | Fills the page the run waits for |
 | `runs.review(runId, stepId, action)` | Accepts a review, or asks for one of the shown steps again with a note |
-| `runs.answerAsk(runId, askId, "allow" \| "skip")` | Answers a running step's question. A sign-in cannot be answered here: hand off |
+| `runs.answerAsk(runId, askId, "allow" \| "skip")` | Answers a running step’s question. A sign-in cannot be answered here: hand off |
 | `runs.control(runId, "back" \| "retry" \| "cancel")` | |
 | `runs.subscribe(runId, listener)` | Hears every change of the run: its events with their note in both languages, or a status change. Returns the function that stops it |
-| `runs.handoffUrl(runId)` | The run page with the run's ticket: the link to send for what the door cannot do. The person who opens it and the door's person are one to the wizard |
+| `runs.handoffUrl(runId)` | The run page with the run’s ticket: the link to send for what the door cannot do. The person who opens it and the door’s person are one to the wizard |
 | `runs.upload(runId, { data, mime, name })` | A file of the person; the asset id goes into an image or file field with `answerPage` |
-| `runs.transcribe(runId, { data, mime })` | What is said in a recording of the person (a voice message), written down with the tenant's audio model and charged to the run. Up to 10 MB |
+| `runs.transcribe(runId, { data, mime })` | What is said in a recording of the person (a voice message), written down with the tenant’s audio model and charged to the run. Up to 10 MB |
 
 A refused command throws an error with a `status` and a `code` (`not_found`, `invalid`,
 `refused`, `no_credits`); an `invalid` one also carries the fields that did not fit as
@@ -107,12 +108,12 @@ A refused command throws an error with a `status` and a `code` (`not_found`, `in
 
 ## What the person sees
 
-- The wizard's first page offers the runners that are on beside "Let's go".
+- The wizard’s first page offers the runners that are on beside “Let’s go”.
 - A hand-off is a link to the same run; nothing is asked twice. The run page knows the
-  door's person through the run, and "What this wizard remembers" is theirs there too.
-- The space's results carry the door a run came through.
+  door’s person through the run, and “What this wizard remembers” is theirs there too.
+- The space’s results carry the door a run came through.
 
-## The runner's part of the share dialog
+## The runner’s part of the share dialog
 
 The row of a channel runner, with its number, keyword, link and QR code, comes from its
 `address`. What the owner changes per wizard, such as the keyword, the studio half registers as
@@ -132,8 +133,8 @@ go into a [settings section](./studio.md).
 
 ### Setting up inside the dialog
 
-What "Einrichten" in a row opens: without more, the plugin's settings section. A setup the studio
-half registers opens inside the dialog instead, as a view with a back arrow, at the dialog's
+“Set up” in a row opens the plugin’s settings section, unless the studio half registers a
+setup. That setup opens inside the dialog instead, as a view with a back arrow, at the dialog’s
 height:
 
 ```tsx
@@ -149,21 +150,21 @@ function Setup({ wizard, Actions, done }: StudioShareSetupProps) {
     <>
       <p>…</p>
       <Actions>
-        <Button onClick={() => ask.mutate()}>Nummer anfragen</Button>
+        <Button onClick={() => ask.mutate()}>{t("request")}</Button>
       </Actions>
     </>
   );
-  // done({ title: "Nummer angefragt", text: "…", tone: "waiting" }) goes back.
+  // done({ title: t("requested"), text: "…", tone: "waiting" }) goes back.
 }
 ```
 
 | | |
 |---|---|
-| `title` | The view's heading, a function: the language can change |
-| `component` | Gets `{ wizard: { id, title }, Actions, done }`. What it renders inside `Actions` goes to the foot of the dialog, where the dialog's own buttons are. `done(banner?)` goes back to the main view and asks the rows again; `banner` (`{ title, text?, tone? }`, `tone` `done` green or `waiting` plain) shows on top |
-| `notice` | Optional: a banner above the rows while the runner has news ("Deine Nummer ist da"), drawn by the plugin, nothing while it has none. Gets `{ wizard, open }`; `open()` opens the setup. The dialog shows the first one of the runners that are on |
+| `title` | The view’s heading, a function: the language can change |
+| `component` | Gets `{ wizard: { id, title }, Actions, done }`. What it renders inside `Actions` goes to the foot of the dialog, where the dialog’s own buttons are. `done(banner?)` goes back to the main view and asks the rows again; `banner` (`{ title, text?, tone? }`, `tone` `done` green or `waiting` plain) shows on top |
+| `notice` | Optional: a banner above the rows while the runner has news (“Your number is here”), drawn by the plugin. It draws nothing while there is no news. It gets `{ wizard, open }`; `open()` opens the setup. The dialog shows the banner of the first runner that is on |
 
-One setup per runner. A setup that asks the server for something calls the plugin's own routes;
+One setup per runner. A setup that asks the server for something calls the plugin’s own routes;
 the rows show what `problem` answers after `done`.
 
 ## A thread door from the SDK
@@ -180,7 +181,7 @@ const surface: ThreadSurface = {
   runner: "sms",
   asks: ["text", "number", "select", "multiselect", "toggle", "date", "email", "url", "location"],
   async send(thread, prompt) {
-    // prompt.kind: "text" | "choice" | "location" | "link" | "media" — draw it as the channel allows.
+    // prompt.kind: "text" | "choice" | "location" | "link" | "media": draw it as the channel allows.
     await twilio.send(thread.id, toText(prompt, thread.state.lang));
   },
 };
@@ -194,20 +195,24 @@ const door = new ThreadDoor({ runs: server.runs, surface, offered, watch, unwatc
 | `ThreadSurface.asks` | The field kinds the thread asks itself; a page with any other field goes to the screen as a link |
 | `send(thread, prompt)` | A `choice` is drawn as buttons, a list or numbered lines; a typed number or title counts as a tap, the door works that out. `link` and `media` carry a URL |
 | `media(ref)` | A file the person sent, by what the webhook named; without it files hand off |
-| `mayDeliver`, `reach` | A messenger with a window (WhatsApp's 24 hours): whether a free message may go out now, and the link by other means when not |
+| `mayDeliver`, `reach` | A messenger with a window (WhatsApp’s 24 hours): whether a free message may go out now, and the link by other means when not |
 | `offered()` | The wizards switched on for the runner (`runs.wizards`) with their keywords; a keyword in the thread starts its wizard, else the door offers the menu |
 | `watch(thread)`, `unwatch(runId)` | Hear the run (`runs.subscribe`) and call `door.resume` when it moves; the plugin keeps the subscriptions |
 | `Thread` | `{ id, name, runId, state, lastInboundAt, lastMessageId }`: the plugin keeps it in a table per person and hands it to the door before and after |
 
+Once a wizard runs, the door speaks the wizard’s language. Before that, it speaks the language
+all offered wizards share; when they differ, it keeps the language it spoke last, which is
+English in a new thread.
+
 A messenger plugin is a surface of this door: the webhook on a public route, the keyword table,
-the number and the keyword in the share dialog are the plugin's; buttons and lists, or numbered
+the number and the keyword in the share dialog are the plugin’s; buttons and lists, or numbered
 lines and links, are its surface.
 
 ## A call
 
-A call has no thread and no screen: the person and a realtime speech model talk, and the
-model fills the run through tools, as the chat's live voice does in the browser. The runtime
-hands a plugin the tenant's speech model for it:
+A call has no thread and no screen: the person talks with a realtime speech model, and the
+model fills the run through tools, as the chat’s live voice does in the browser. The runtime
+hands a plugin the tenant’s speech model for it:
 
 ```ts
 const { apiKey, model } = await server.speech.conversation();
@@ -215,9 +220,9 @@ const { apiKey, model } = await server.speech.conversation();
 ```
 
 A call plugin keeps the audio out of the runtime: the telephony provider hands the call to the
-speech model's SIP endpoint with a token in a header, the model's provider posts the incoming
-call to the plugin's public route, and the plugin accepts it with the wizard's rules and tools
-and answers the model's tool calls over a WebSocket, driving the run with `server.runs`. What a
+speech model’s SIP endpoint with a token in a header, the model’s provider posts the incoming
+call to the plugin’s public route, and the plugin accepts it with the wizard’s rules and tools
+and answers the model’s tool calls over a WebSocket, driving the run with `server.runs`. What a
 voice cannot take goes out as a link.
 
 ## Not there yet

package/apps/runtime/dist/docs/dev/plugins/server.md

@@ -1,7 +1,7 @@
 ---
 title: The server half
 description: The function a plugin exports, what it is handed, and the rules it runs under.
-version: 0.4.4
+version: 0.5.0
 ---
 
 The server half is a file whose default export is a function. The runtime calls it once when the
@@ -29,7 +29,8 @@ export default definePlugin((wizards) => {
 | `wizards.server` | Registers tools, routes, tables and listeners. See the table below |
 | `wizards.plugin` | The manifest: `id`, `name`, `version` and whatever else it holds |
 | `wizards.config.get(key)` | A setting of the install: a line of its `.env`. Empty and missing are both `undefined` |
-| `wizards.log.info`, `.warn`, `.error` | A log line with the plugin's name in front |
+| `wizards.features.has(name)`, `.all()` | The feature switches of the tenant at hand. See [Feature switches](#feature-switches) |
+| `wizards.log.info`, `.warn`, `.error` | A log line with the plugin’s name in front |
 | `wizards.resolvePath(relative)` | A file of the plugin as an absolute path |
 
 | `wizards.server.` | Does | Page |
@@ -37,32 +38,33 @@ export default definePlugin((wizards) => {
 | `registerTool(tool)` | A tool for AI steps | [Tools](./tools.md) |
 | `registerSpaceContext(context)` | A block and tools for every AI step of a space | [The space](./space.md) |
 | `registerAssistantTool(tool)` | A tool of the space assistant | [The space](./space.md#tools-of-the-space-assistant) |
-| `registerAssistantContext(context)` | What the space assistant is told on the plugin's own page | [The space](./space.md#the-assistant-on-the-plugins-own-page) |
-| `spaceData.putPage(input)`, `putTable`, `putFile`, `putDocument`, `putCategories`, … | Knowledge of a space: pages, tables, files and Kategorien | [The space](./space.md#knowledge-a-plugin-writes) |
-| `spaces.brand(space)` | The space's look: its title, colours and fonts | [The space](./space.md#the-spaces-brand) |
-| `index.put(entry)`, `index.remove(space, key?)` | Texts in the space's search index | [The space](./space.md#the-search-index) |
+| `registerAssistantContext(context)` | What the space assistant is told on the plugin’s own page | [The space](./space.md#the-assistant-on-the-plugins-own-page) |
+| `spaceData.putPage(input)`, `putTable`, `putFile`, `putDocument`, `putCategories`, … | Knowledge of a space: pages, tables, files and categories | [The space](./space.md#knowledge-a-plugin-writes) |
+| `spaces.brand(space)` | The space’s look: its title, colours and fonts | [The space](./space.md#the-spaces-brand) |
+| `index.put(entry)`, `index.remove(space, key?)` | Texts in the space’s search index | [The space](./space.md#the-search-index) |
 | `registerHttpRoute(route)` | A route below `/api/studio/plugins/<id>` | [Routes](./routes.md) |
 | `registerPublicRoute(route)`, `publicUrl(path)` | A route anyone may call, and its address | [Routes](./routes.md#public-routes) |
 | `registerSharedRoute(route)`, `sharedUrl(path)`, `publicRef()` | One route for every tenant, and the ref that names one | [Routes](./routes.md#shared-routes) |
 | `channels.get()`, `request`, `withdraw`, `book` | The numbers the Manage-App gives the tenant | below |
+| `claims.take(key)`, `put`, `drop`, `holder`, `mine` | Keys held across tenants, one tenant each | below |
 | `registerRunner(runner)` | A door a wizard runs through, beside the page and the chat | [Runners](./runners.md) |
-| `runs.start(…)`, `report`, `answerPage`, … | Drives runs from the plugin's own door | [Runners](./runners.md#drive-a-run) |
-| `speech.conversation()` | The tenant's realtime speech model, for a call | [Runners](./runners.md#a-call) |
-| `registerMigrations(folder)` | `.sql` files with the plugin's tables | [Tables](./tables.md) |
+| `runs.start(…)`, `report`, `answerPage`, … | Drives runs from the plugin’s own door | [Runners](./runners.md#drive-a-run) |
+| `speech.conversation()` | The tenant’s realtime speech model, for a call | [Runners](./runners.md#a-call) |
+| `registerMigrations(folder)` | `.sql` files with the plugin’s tables | [Tables](./tables.md) |
 | `on(event, listener)` | Called when a run ends or a space changes | [Events](./events.md) |
 | `connections.available(…)`, `start`, `connect`, `list`, `call`, … | Accounts of a space, through the built-in connectors | [Accounts](./connections.md) |
 | `registerStarter(starter)` | A wizard the plugin brings as a template | [Starters](./starters.md) |
 | `every(name, everyMs, handler)` | A job, again and again | below |
 | `web.fetch(url, init?)`, `web.read(url)` | Requests to the web, guarded | below |
 | `documents.parse(file)` | A file as Markdown | below |
-| `secrets.seal(value)`, `secrets.unseal(sealed)` | Keys of the plugin's own, sealed for a table | below |
+| `secrets.seal(value)`, `secrets.unseal(sealed)` | Keys of the plugin’s own, sealed for a table | below |
 | `getTenantDb()` | The database of the tenant the current request, step or event belongs to | [Tables](./tables.md) |
 | `generate(request)` | Asks a model of the current tenant | below |
 | `onUnload(fn)` | Something to undo when the plugin unloads | below |
 
 ## Settings
 
-Name a plugin's settings after the plugin and read them when the plugin loads:
+Name a plugin’s settings after the plugin and read them when the plugin loads:
 
 ```ts
 const url = wizards.config.get("NOTIFY_URL");
@@ -72,17 +74,35 @@ if (!url) {
 }
 ```
 
-The person sets them in the install's `.env` and restarts. There is no settings page a plugin
-gets for free: a plugin that wants one adds a [settings section](./studio.md) and keeps the
-values in a [table](./tables.md).
+The person sets them in the install’s `.env` and restarts engenty wizards. A plugin doesn’t get
+a settings page for free: a plugin that wants one adds a [settings section](./studio.md) and
+keeps the values in a [table](./tables.md).
+
+## Feature switches
+
+A plugin declares its own switches in its manifest under `features`
+([Files and manifest](./layout.md#the-manifest)). Everywhere else each one is known as
+`<plugin id>.<name>`: in `wizards features`, in the install’s `.features` file and in the
+`FEATURES` setting.
+
+```ts
+if (await wizards.features.has("leadScoring")) {
+  server.registerTool(scoreLead);
+}
+```
+
+- `has(name)` with a short name asks for the plugin’s own switch (`contacts.leadScoring`); a
+  full name asks for any switch, the runtime’s own included.
+- `all()` gives every switch of the tenant at hand, by its full name.
+- A switch is off unless something turned it on.
 
 ## Tenants
 
-A runtime serves one tenant on a person's computer and many on engenty.ai.
-Either way a plugin never names a tenant:
+A runtime serves one tenant on a person’s computer and many on engenty.ai. Either way, a plugin
+never names a tenant:
 
 - A route, a tool and a listener each run inside one tenant.
-- `server.getTenantDb()` is that tenant's database. Call it where you use it, not once at load
+- `server.getTenantDb()` is that tenant’s database. Call it where you use it, not once at load
   time: at load time there is no tenant.
 - State kept in a variable of the module is shared by all tenants. Keep per-tenant state in a
   table.
@@ -91,7 +111,7 @@ Either way a plugin never names a tenant:
 
 On engenty.ai a team gets its number for texts and calls from engenty: it asks for one, an
 admin assigns it. `server.channels` reads it for the current tenant and books what it carries;
-the prices are the Manage-App's ([manage contract](https://github.com/engenty/wizards/blob/main/docs/manage-contract.md#numbers-of-a-tenant)).
+the prices are the Manage-App’s ([manage contract](https://github.com/engenty/wizards/blob/main/docs/manage-contract.md#numbers-of-a-tenant)).
 
 ```ts
 const channels = await server.channels.get();
@@ -106,15 +126,46 @@ await server.channels.book({ kind: "sms", quantity: segments, key: messageSid, r
 
 - `get` is kept for a minute; `request` and `withdraw` forget it.
 - `request` throws `403` / `plan` on a plan without a number and `409` / `has_number` when
-  the team has one. Asking again answers the open request.
-- `book`: `sms` by segment, sent or received, `call` by started minute. The same `key` books
-  once.
+  the team has one. Asking again gives the open request.
+- `book`: `sms` by segment, sent or received, `call` by started minute, `whatsapp` by
+  message sent. The same `key` books once.
 - A runtime without a Manage-App has no numbers: `get` gives `null`, `request` and `withdraw`
   throw `404` / `not_managed`, `book` books nothing.
 
+## Keys across tenants
+
+What a [shared route](./routes.md#shared-routes) needs to find its tenant: a keyword on a number
+every tenant shares, who last wrote to it, a number a tenant connected. `server.claims` holds
+such keys, each for one tenant at a time, in the runtime’s own database:
+
+```ts
+// In the tenant: the keyword is this tenant's, unless another one has it.
+if (!(await server.claims.take(`kw:${keyword.toLowerCase()}`))) {
+  throw Object.assign(new Error("Taken."), { status: 409, code: "keyword_taken" });
+}
+await server.claims.put(`sender:${waId}`); // the last tenant they wrote to has them
+
+// In the shared route: whose is it?
+const ref = await server.claims.holder(`kw:${text.toLowerCase()}`);
+if (ref) {
+  await inTenant(ref, () => handle(message));
+}
+```
+
+| | |
+|---|---|
+| `take(key)` | The current tenant takes the key; `false` when another tenant holds it |
+| `put(key)` | The current tenant gets the key, whoever held it |
+| `drop(key)` | The current tenant gives the key up; a key another tenant holds stays |
+| `holder(key)` | The ref of the tenant that holds the key, for `inTenant`; `null` for none. Also outside a tenant |
+| `mine(key)` | Whether the current tenant holds the key |
+
+Keys are 1 to 200 characters and the plugin’s own: another plugin’s key of the same name is
+another key. They stay when a tenant loses the plugin; `inTenant` then answers `404`.
+
 ## Asking a model
 
-`server.generate` asks one of the tenant's models, the same ones its wizards run on, and is paid
+`server.generate` asks one of the tenant’s models, the same ones its wizards run on, and is paid
 like any other of its calls. With a `schema` the answer is an object of that shape:
 
 ```ts
@@ -132,13 +183,13 @@ const { object } = await server.generate({
 | `system` | How it should answer | |
 | `schema` | A zod schema: `object` is the answer in that shape | text only |
 | `model` | `classifier` (fast, cheap), `standard`, `high`, `highest` | `standard` |
-| `maxOutputTokens` | A limit on the answer | the model's |
+| `maxOutputTokens` | A limit on the answer | the model’s |
 | `signal` | Aborts the call | two minutes |
 | `files` | Pictures (PNG, JPEG, WebP, GIF) and PDFs the model looks at with the prompt: `{ data, mediaType, name? }[]`, `data` a `Uint8Array` | none |
 
 It answers `{ text, object }`. Without a model set up it throws an error with the status `503`
 and the code `no_model`: a route that lets it through answers just that, and the studio half
-says it in the person's language.
+says it in the person’s language.
 
 ## Jobs
 
@@ -151,11 +202,11 @@ server.every("refresh", 60 * 60_000, async ({ tenantId, lastRun, signal }) => {
 ```
 
 - The handler runs for every tenant that has the plugin, inside that tenant, at most once per
-  `everyMs`. A minute is the least.
-- A job's name is lower case, digits and `_`, once per plugin.
-- When it ran is kept: a restart does not start the count again. A runtime that was off runs a
-  due job once when it starts, not once per turn it missed. A local install runs jobs while it
-  runs.
+  `everyMs`. The shortest interval is a minute.
+- A job’s name is lower case, digits and `_`, once per plugin.
+- The runtime keeps when a job ran, so a restart does not start the count again. A runtime that
+  was off runs a due job once when it starts, not once per turn it missed. On a person’s computer,
+  jobs run while engenty wizards runs.
 - One turn per tenant at a time. A turn that throws is logged and counts as run.
 - `lastRun` is when the turn before started; `null` the first time. `signal` is aborted
   when the plugin unloads.
@@ -172,20 +223,20 @@ const res = await server.web.fetch(`${origin}/sitemap.xml`, {
 });
 ```
 
-- Both refuse addresses of this machine and of the local network, after a redirect too, as the
-  runtime's own requests do.
-- `read` gives the page's text as Markdown and its links, absolute and each once (up to
+- Both refuse addresses of the computer the runtime runs on and of its local network, after a
+  redirect too, as the runtime’s own requests do.
+- `read` gives the page’s text as Markdown and its links, absolute and each once (up to
   2,000). A page with hardly any text without its scripts is drawn in a browser first. `etag`
   and `lastModified` are what the server sent, for asking later whether the page changed. `jsonld`
-  is the page's structured data (its `application/ld+json` blocks, parsed): a shop's product
+  is the page’s structured data (its `application/ld+json` blocks, parsed): a shop’s product
   page says title, price, availability and image there exactly, without a model.
 - `fetch` is `fetch` behind the guard: for a sitemap, `robots.txt`, a question with
   `if-none-match`.
 
-## Keys of the plugin's own
+## Keys of the plugin’s own
 
 A plugin that talks to a shop or a service with keys the person typed keeps them sealed, as the
-runtime seals a connection's tokens:
+runtime seals a connection’s tokens:
 
 ```ts
 await db().update(store).set({ credentials: server.secrets.seal({ token }) });
@@ -200,8 +251,9 @@ const keys = server.secrets.unseal<{ token: string }>(row.credentials);
 const { markdown, pages } = await server.documents.parse({ data, name: "preise.pdf", mime });
 ```
 
-PDF and Word files by their own text, scans and photos by a vision model, spreadsheets and CSV as
-tables. What was read is kept by content: the same bytes are read, and paid for, once.
+PDF and Word files are read by their own text, scans and photos by a vision model, and
+spreadsheets and CSV files as tables. What was read is kept by content, so the same bytes are
+read, and paid for, only once.
 
 ## Undo on unload
 
@@ -217,13 +269,13 @@ The functions run last-first when the plugin unloads or loads again.
 
 ## When loading fails
 
-A plugin whose function throws keeps nothing of what it registered before the error: no half
-plugins. Settings → Plugins shows the error, and the plugin's routes answer `404` until its file
-is mended.
+A plugin whose function throws keeps nothing of what it registered before the error, so there
+are no half-loaded plugins. Settings → Plugins shows the error, and the plugin’s routes answer
+`404` until you fix its file.
 
 ## Imports
 
 `@engenty-wizards/plugin-sdk` (and `@engenty-wizards/plugin-sdk/thread`), `zod`, `drizzle-orm` and
-`drizzle-orm/sqlite-core` come from the
-runtime's own copies, so a schema or a table a plugin makes is one the runtime understands. See
-[Files and manifest](./layout.md#dependencies) for everything else.
+`drizzle-orm/sqlite-core` come from the runtime’s own copies, so a schema or a table a plugin
+makes is one the runtime understands. See [Files and manifest](./layout.md#dependencies) for
+everything else.

package/apps/runtime/dist/docs/dev/plugins/shipping.md

@@ -1,12 +1,12 @@
 ---
 title: Shipping
 description: Hand a plugin to someone else, put it into a server's image, and decide which tenant has it.
-version: 0.3.2
+version: 0.5.0
 ---
 
-## To someone's install
+## To someone’s install
 
-A plugin is a file or a folder. Whoever installs it puts it into their plugins folder:
+A plugin is a file or a folder. Whoever installs it puts it into their plugins folder, which is
 `~/.engenty/wizards/plugins` for an installed app.
 
 Give them:
@@ -18,7 +18,7 @@ Give them:
 | Dependencies | A `node_modules` beside the plugin, if it imports anything but the SDK, `zod` and `drizzle-orm` |
 | Settings | The names of the `.env` lines it reads, in its description |
 
-Say what it does with data: a plugin runs with the app's full rights, and the person who
+Say what the plugin does with data. A plugin runs with the app’s full rights, and the person who
 installs it trusts you with them.
 
 ## As a package
@@ -31,8 +31,8 @@ npm install @acme/wizards-contacts
 ```
 
 The runtime finds `node_modules/@acme/wizards-contacts/engenty.plugin.json` at its next start,
-or with "Look again" in Settings → Plugins. Put the manifest, the server half and the built
-`dist/` into the package's `files`.
+or with “Look again” in Settings → Plugins. Put the manifest, the server half and the built
+`dist/` into the package’s `files`.
 
 ## Into a server
 
@@ -47,17 +47,20 @@ services:
       - ./plugins:/plugins
 ```
 
-Or copy the plugins into an image of your own, built on the runtime's.
+Or copy the plugins into an image of your own, built on the runtime’s.
 
 ## With engenty wizards itself
 
-Plugins in the repository's `modules/` folder ship with every runtime: in a checkout, in the
-installed app and in the Docker image. A module there is part of the open product.
+Plugins in the repository’s `modules/` folder ship with every runtime: in a checkout, in the
+npm package and installed app, and in the Docker image. A module there is part of the open
+product.
 
-- Its server half imports only what the runtime hands every plugin and its own files. It has no
+- Its server half imports only what the runtime hands every plugin, and its own files. It has no
   `node_modules` of its own where it is installed.
 - A module with a studio half is a workspace package whose `build` script is
-  `node ../../scripts/build-plugin.mjs .`, so the product's build builds its `dist/`.
+  `node ../../scripts/build-plugin.mjs .`, so the product’s build builds its `dist/`.
+  `apps/runtime/Dockerfile` copies each workspace package’s `package.json` before it installs:
+  add the module’s there.
 
 A plugin that is not part of the open product stays out of `modules/` and goes into a folder of
 `PLUGINS_DIR`.
@@ -66,11 +69,11 @@ A plugin that is not part of the open product stays out of `modules/` and goes i
 
 On an install of your own, on your computer or your own server, every tenant has every plugin
 the runtime loaded. On engenty.ai the service installs the plugins and switches them on per
-account; a person cannot install one there.
+account. A person cannot install a plugin there.
 
 ## Versions
 
-- `version` in the manifest is shown in the settings. The runtime does not compare versions.
-- A plugin's `.sql` files only ever grow: an update adds files, it never changes one that ran.
-- A wizard that uses a plugin's tool names it by id. Renaming a tool or the plugin breaks those
-  wizards: keep ids for good.
+- The settings show `version` from the manifest. The runtime doesn’t compare versions.
+- A plugin’s `.sql` files only ever grow: an update adds files and never changes one that ran.
+- A wizard that uses a plugin’s tool names it by its id. Renaming a tool or the plugin breaks
+  those wizards, so keep ids for good.