wizards 0.4.7 → 0.5.1

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

@@ -1,15 +1,15 @@
 ---
 title: Reference
 description: Every call, type, address and setting of the plugin framework on one page.
-version: 0.4.4
+version: 0.5.0
 ---
 
 ## Server half
 
 `import { definePlugin } from "@engenty-wizards/plugin-sdk"`
 
-`import { ThreadDoor } from "@engenty-wizards/plugin-sdk/thread"` — a wizard run in a
-messenger's thread, one message at a time; a plugin brings the surface. See
+`import { ThreadDoor } from "@engenty-wizards/plugin-sdk/thread"`: a wizard run in a
+messenger’s thread, one message at a time, for which a plugin brings the surface. See
 [Runners](./runners.md#a-thread-door-from-the-sdk).
 
 The default export is a `WizardsPluginFactory`: `(wizards: WizardsPluginApi) => void | Promise<void>`.
@@ -20,8 +20,9 @@ The default export is a `WizardsPluginFactory`: `(wizards: WizardsPluginApi) =>
 |---|---|---|
 | `plugin` | `PluginManifest` | The manifest |
 | `server` | `PluginServerApi` | Below |
-| `config.get(key)` | `string \| undefined` | A setting of the install |
-| `log.info`, `log.warn`, `log.error` | `(...args) => void` | A log line with the plugin's name |
+| `config.get(key)` | `string \| undefined` | A setting of the install: a line of its `.env` |
+| `features.has(name)`, `features.all()` | `Promise<boolean>`, `Promise<Record<string, boolean>>` | The tenant’s feature switches. A short name is the plugin’s own switch from its manifest (`<id>.<name>`); a full name asks for any switch. Off unless something turned it on |
+| `log.info`, `log.warn`, `log.error` | `(...args) => void` | A log line with the plugin’s name |
 | `resolvePath(relative)` | `string` | A file of the plugin as an absolute path |
 
 ### `wizards.server`
@@ -30,29 +31,30 @@ The default export is a `WizardsPluginFactory`: `(wizards: WizardsPluginApi) =>
 |---|---|
 | `registerTool(tool: PluginTool)` | [Tools](./tools.md) |
 | `registerRunner(runner: PluginRunner)` | [Runners](./runners.md). A door a wizard runs through; `page` runners answer at `/w/<token>/<id>` |
-| `runs` | [Runners](./runners.md#drive-a-run). `start`, `report`, `wizards`, `answerPage`, `review`, `answerAsk`, `control`, `subscribe`, `handoffUrl`, `upload`, `transcribe`: the functions behind the MCP tools, for the plugin's door |
-| `speech.conversation()` | [Runners](./runners.md#a-call). `{ provider: "openai", apiKey, model }`: the tenant's realtime speech model, for a call a plugin drives itself. Throws `503` / `no_model` while none is set up |
+| `runs` | [Runners](./runners.md#drive-a-run). `start`, `report`, `wizards`, `answerPage`, `review`, `answerAsk`, `control`, `subscribe`, `handoffUrl`, `upload`, `transcribe`: the functions behind the MCP tools, for the plugin’s door |
+| `speech.conversation()` | [Runners](./runners.md#a-call). `{ provider: "openai", apiKey, model }`: the tenant’s realtime speech model, for a call a plugin drives itself. Throws `503` / `no_model` while none is set up |
 | `registerSpaceContext({ block, tools?, steps? })` | [The space](./space.md). `block(space): string \| null`; `steps`: `agent` (default), `html` (steps that write a document or a dashboard, without the tools) |
 | `spaces.brand(space)` | [The space](./space.md#the-spaces-brand). `{ name, colors, fonts }` of the space, or `null` |
 | `registerAssistantTool(tool: PluginAssistantTool)` | [The space](./space.md#tools-of-the-space-assistant) |
 | `index.put({ space, key, title, text, link? })`, `index.remove(space, key?)` | [The space](./space.md#the-search-index) |
-| `spaceData.putCategories`, `.putPage`, `.putTable`, `.putFile`, `.putDocument`, `.list`, `.readPages`, `.files`, `.readFile`, `.remove`, `.summarize` | [The space](./space.md#knowledge-a-plugin-writes). Knowledge of a space: pages, tables and files under keys of the plugin's own, with their Kategorien; and the space's own pages and files to read |
+| `spaceData.putCategories`, `.putPage`, `.putTable`, `.putFile`, `.putDocument`, `.list`, `.readPages`, `.files`, `.readFile`, `.remove`, `.summarize` | [The space](./space.md#knowledge-a-plugin-writes). Knowledge of a space: pages, tables and files under keys of the plugin’s own, with their categories; and the space’s own pages and files to read |
 | `registerHttpRoute(route: PluginRoute)` | [Routes](./routes.md) |
 | `registerPublicRoute(route: PluginPublicRoute)` | [Routes](./routes.md#public-routes) |
 | `publicUrl(path): Promise<string>` | The full address of a public route for the current tenant |
 | `publicRef(): Promise<string>` | [Routes](./routes.md#shared-routes). The part of `publicUrl` that names the current tenant |
 | `registerSharedRoute(route: PluginSharedRoute)` | [Routes](./routes.md#shared-routes). One route for every tenant; `handler({ request, path, params, query, inTenant })` |
 | `sharedUrl(path): string` | The full address of a shared route, the same for every tenant |
-| `channels.get()`, `.request({ userId, country, wish?, lang })`, `.withdraw()`, `.book({ kind, quantity, key, runId? })` | [Numbers of the Manage-App](./server.md#numbers-of-the-manage-app). `get`: `{ number, request, shared, allowed }` or `null` without a Manage-App |
-| `registerMigrations(folder: string)` | [Tables](./tables.md). The folder is relative to the plugin's |
+| `claims.take(key)`, `.put(key)`, `.drop(key)`, `.holder(key)`, `.mine(key)` | [Keys across tenants](./server.md#keys-across-tenants). Each key for one tenant at a time; `holder` gives the tenant’s ref for `inTenant` |
+| `channels.get()`, `.request({ userId, country, wish?, lang })`, `.withdraw()`, `.book({ kind: "sms" \| "call" \| "whatsapp", quantity, key, runId? })` | [Numbers of the Manage-App](./server.md#numbers-of-the-manage-app). `get`: `{ number, request, shared, allowed }` or `null` without a Manage-App |
+| `registerMigrations(folder: string)` | [Tables](./tables.md). The folder is relative to the plugin’s |
 | `on(event, listener)` | [Events](./events.md). `event`: `"run.done"`, `"run.failed"`, `"run.cancelled"`, `"space.created"`, `"space.updated"`, `"space.deleted"`, `"space.file.ready"`, `"space.file.removed"` |
 | `every(name, everyMs, handler)` | [Jobs](./server.md#jobs). Per tenant that has the plugin, at most once per `everyMs` (a minute at least). `handler({ tenantId, lastRun, signal })` |
 | `web.fetch(url, init?)`, `web.read(url, { signal? })` | [The web](./server.md#the-web) |
 | `documents.parse({ data, name, mime }, { signal? })` | [Documents](./server.md#documents). `{ markdown, pages }` |
-| `getTenantDb(): PluginDb` | The current tenant's database, a Drizzle libSQL database |
+| `getTenantDb(): PluginDb` | The current tenant’s database, a Drizzle libSQL database |
 | `generate(request): Promise<{ text, object }>` | Asks a model of the current tenant: `prompt`, `system?`, `schema?`, `model?`, `maxOutputTokens?`, `signal?`, `files?` (pictures and PDFs: `{ data, mediaType, name? }[]`). See [The server half](./server.md#asking-a-model) |
-| `connections.available(ids)`, `.start({ space, connector, actions })`, `.connect({ space, connector, actions, credentials })`, `.list(space)`, `.get(id)`, `.call(id, action, input)`, `.remove(id)` | [Accounts](./connections.md) |
-| `secrets.seal(value): string`, `secrets.unseal(sealed)` | [Keys of the plugin's own](./server.md#keys-of-the-plugins-own). `unseal` gives null for a value sealed on another install |
+| `connections.available(ids)`, `.start({ space, connector, actions, lang? })`, `.connect({ space, connector, actions, credentials })`, `.list(space)`, `.get(id)`, `.call(id, action, input)`, `.remove(id)` | [Accounts](./connections.md). `lang`: the language of the page the person comes back to |
+| `secrets.seal(value): string`, `secrets.unseal(sealed)` | [Keys of the plugin’s own](./server.md#keys-of-the-plugins-own). `unseal` gives null for a value sealed on another install |
 | `registerAssistantContext({ block })` | [The space](./space.md#the-assistant-on-the-plugins-own-page). `block(space): string \| null` |
 | `registerStarter(starter: PluginStarter)` | [Starters](./starters.md). Known as `<plugin id>.<starter id>` |
 | `onUnload(fn)` | Runs when the plugin unloads or loads again |
@@ -97,11 +99,18 @@ interface PluginRunner {
     handoff: ("screen" | "thread" | "sms" | "push")[];
   };
   page?(request: PluginRunnerRequest): Response | Promise<Response>;
-  problem?(): string | null | Promise<string | null>;  // why not usable in this tenant right now
+  problem?(): string | PluginRunnerProblem | null | Promise<string | PluginRunnerProblem | null>;  // why not usable in this tenant right now
   address?(wizard: { id: string; title: string; token: string }):
     | PluginRunnerAddress | null | Promise<PluginRunnerAddress | null>;  // where a person reaches the wizard
 }
 
+interface PluginRunnerProblem {
+  text: string;                           // in the owner's words
+  kind?: "setup" | "waiting" | "plan";    // default "setup"
+  note?: { de: string; en: string };      // what the share dialog's row says instead
+  plan?: string;                          // "plan": the plan that has it
+}
+
 interface PluginRunnerAddress {
   number?: string | null;   // the number people write to or call, with the country code
   keyword?: string | null;  // the word that picks this wizard on that number
@@ -140,7 +149,7 @@ interface PluginRuns {
 ```
 
 `waitSeconds` is at most 45. `draft`: the answers a door has so far for the page shown, so a
-field's `shown` follows them. `wizards(runner)`: the published wizards that switched the runner
+field’s `shown` follows them. `wizards(runner)`: the published wizards that switched the runner
 on. `transcribe`: a recording of the person written down, charged to the run.
 
 `PluginRunReport` is what `get_run` gives an MCP client: status, the step, `waitingFor` (a
@@ -214,7 +223,7 @@ interface PluginStarter {
   id: string;                    // lower case, digits and "-"
   title: string;
   description: string;           // what it makes, in one or two sentences
-  language?: "de" | "en";        // the language of its texts; default "de"
+  language?: "de" | "en";        // the language of its texts; default "en"
   definition: unknown;           // a complete wizard definition, checked when it is registered
   files?: Record<string, string | Uint8Array>;  // workspace files by path; a string is UTF-8
 }
@@ -242,20 +251,20 @@ The default export is a `StudioPlugin`: `(studio: StudioPluginContext) => void`.
 | `studio.registerPage({ path, component, wide? })` | A page at `/studio<path>` |
 | `studio.registerNav({ to, label, icon })` | An icon in the app bar. `label: () => string` |
 | `studio.registerSettingsSection({ id, label, icon, component, menu? })` | A section at `/studio/settings/<id>` |
-| `studio.registerShareSection({ runner, component })` | [Runners](./runners.md#the-runners-part-of-the-share-dialog). The runner's own settings for a wizard (a keyword), under the share dialog's gear once it is switched on and set up. `component` gets `{ wizard: { id, title } }` |
-| `studio.registerShareSetup({ runner, title, component, notice? })` | [Runners](./runners.md#setting-up-inside-the-dialog). What "Einrichten" in the runner's row opens inside the share dialog. `component` gets `{ wizard, Actions, done(banner?) }`, `notice` `{ wizard, open }` |
-| `studio.registerAssistantCard({ tool, component })` | Draws a tool's result in the space assistant's chat. `component` gets `{ data, send }` |
+| `studio.registerShareSection({ runner, component })` | [Runners](./runners.md#the-runners-part-of-the-share-dialog). The runner’s own settings for a wizard (a keyword), under the share dialog’s gear once it is switched on and set up. `component` gets `{ wizard: { id, title } }` |
+| `studio.registerShareSetup({ runner, title, component, notice? })` | [Runners](./runners.md#setting-up-inside-the-dialog). What “Set up” in the runner’s row opens inside the share dialog. `component` gets `{ wizard, Actions, done(banner?) }`, `notice` `{ wizard, open }` |
+| `studio.registerAssistantCard({ tool, component })` | Draws a tool’s result in the space assistant’s chat. `component` gets `{ data, send }` |
 | `studio.registerSpaceSection({ id, group?, label, hint?, component })` | A section of a part of the space page at `/studio/space/<group>#<id>`; `group`: `info`, `knowledge` (default), `data` or `results` |
-| `studio.registerSpacePart({ id, label, icon, after?, component })` | [A part of the plugin's own](./studio.md#a-part-of-the-plugins-own) at `/studio/space/<id>`, after `info`, `knowledge` or `data` (default) in the menu |
-| `studio.useSpaceMenu(entries)` | A hook in a plugin's part: its menu, `{ id, label, icon? }[]`, each jumping to the element with that id |
-| `studio.useCrumbs(items)` | A hook: the trail in the top bar for the page shown, `{ label, to? }[]`, instead of a heading of the page's own |
-| `studio.Assistant` | Tells the studio's assistant what to say on a page of the plugin: `title?`, `hello?`, `placeholder?`, `suggestions?: { label, message?, fill? }[]`, `onChanged?`. Draws nothing |
+| `studio.registerSpacePart({ id, label, icon, after?, component })` | [A part of the plugin’s own](./studio.md#a-part-of-the-plugins-own) at `/studio/space/<id>`, after `info`, `knowledge` or `data` (default) in the menu |
+| `studio.useSpaceMenu(entries)` | A hook in a plugin’s part: its menu, `{ id, label, icon? }[]`, each jumping to the element with that id |
+| `studio.useCrumbs(items)` | A hook: the trail in the top bar for the page shown, `{ label, to? }[]`, instead of a heading of the page’s own |
+| `studio.Assistant` | Tells the studio’s assistant what to say on a page of the plugin: `title?`, `hello?`, `placeholder?`, `suggestions?: { label, message?, fill? }[]`, `onChanged?`. Draws nothing |
 | `studio.useAssistantPage(page)` | A hook: what the page shows, for the assistant: `open?: { kind, id?, label }`, `selection?`, `summary?`, `fields?: { id, label, value }[]`, `compact?`, and the words of `studio.Assistant` |
 | `studio.useAssistantTool(name, { description, parameters? }, run)` | A hook: a tool the assistant runs in the page while it is shown, as `<plugin>_<name>`. `parameters`: JSON Schema; `run(args)` returns what the assistant learns |
 | `studio.useSpace()` | A hook: `{ id, name, readOnly, brand }` of the space the studio shows, or `null`; `brand` is `{ name, colors, fonts }` |
-| `studio.i18n.register({ de, en })` | Gives `t(key, vars?)` |
+| `studio.i18n.register({ de, en })` | Gives `t(key, vars?)`. A key missing in the language shown falls back to `de` |
 | `studio.i18n.lang()` | `"de"` or `"en"` |
-| `studio.api.get`, `.post`, `.put`, `.patch`, `.del` | The plugin's own routes |
+| `studio.api.get`, `.post`, `.put`, `.patch`, `.del` | The plugin’s own routes |
 | `studio.me()` | `{ user: { id, name, email }, tenant: { id, role }, mode: "managed" \| "local" }` |
 | `studio.onUnload(fn)` | Runs when the studio half loads again |
 
@@ -269,8 +278,8 @@ The default export is a `StudioPlugin`: `(studio: StudioPluginContext) => void`.
 | Tool name for the model | The id with `_` for `.` and `-` | `run_log_recent` |
 | Starter id | Lower case, digits and `-`, starting with a letter, at most 40 characters | `book` |
 | Starter id in a list of templates | `<plugin id>.<starter id>` | `contacts.follow-up` |
-| Table name | Begins with the plugin's id | `run_log_entry` |
-| Runner id | Lower case, digits and `-`, starting with a letter, at most 24 characters; not `steps`, `chat` or a sub-path of a wizard's address | `kiosk` |
+| Table name | Begins with the plugin’s id | `run_log_entry` |
+| Runner id | Lower case, digits and `-`, starting with a letter, at most 24 characters; not a built-in runner (`steps`, `chat`, `talk`, `video`) or a sub-path of a wizard’s address (`runs`, `icons`) | `kiosk` |
 | Element around what a plugin draws | `data-plugin="<plugin id>"` | |
 
 ## Addresses
@@ -279,39 +288,42 @@ All below `/api/studio/plugins`, all signed in:
 
 | Address | | Who |
 |---|---|---|
-| `GET /` | The tenant's plugins: id, name, version, description, tools, where the built files are, why a server half did not load; and what looked like a plugin and is none | Everyone; what is none: owners and admins, alone |
-| `ALL /<id>/…` | The plugin's own routes | Members of a tenant that has the plugin; `role: "admin"` routes owners and admins |
+| `GET /` | The tenant’s plugins: id, name, version, description, tools, where the built files are, why a server half did not load; and what looked like a plugin and is none | Everyone; what is none: owners and admins, alone |
+| `ALL /<id>/…` | The plugin’s own routes | Members of a tenant that has the plugin; `role: "admin"` routes owners and admins |
 | `GET /-/assets/<id>/client.js`, `/client.css` | The built studio half | Members of a tenant that has the plugin |
 | `GET /-/events` | A stream that says when a plugin loaded again | Everyone, alone |
 | `POST /-/reload` | Loads every plugin again | Owners and admins, alone |
 | `POST /-/reload/<id>` | Loads one plugin again | Owners and admins, alone |
 
-"Alone": where the runtime runs alone, not as the runtime of engenty.ai.
+“Alone”: where the runtime runs on its own, not as the runtime of engenty.ai.
 
 For programs, with an API key or an access token:
 
 | Address | | Who |
 |---|---|---|
-| `ALL /api/v1/plugins/<id>/…` | The plugin's own routes, as the key's person. [With a key](./routes.md#with-a-key) | `GET` with `wizards:read`, the rest with `wizards:write`; `403` `plugin` where the account lacks the plugin |
+| `ALL /api/v1/plugins/<id>/…` | The plugin’s own routes, as the key’s person. [With a key](./routes.md#with-a-key) | `GET` with `wizards:read`, the rest with `wizards:write`; `403` `plugin` where the account lacks the plugin |
 
 And public, nobody signed in:
 
 | Address | |
 |---|---|
-| `ALL /api/public/plugins/<id>/<ref>/…` | A plugin's public routes; `<ref>` names the tenant. `server.publicUrl` gives the full address |
-| `/w/<token>/<runner>` | A plugin's page runner for a wizard that switched it on (built; from source `/api/public/wizards/<token>/runners/<runner>`) |
+| `ALL /api/public/plugins/<id>/<ref>/…` | A plugin’s public routes; `<ref>` names the tenant. `server.publicUrl` gives the full address |
+| `ALL /api/public/plugins/<id>/shared/…` | A plugin’s shared routes, one address for every tenant. `server.sharedUrl` gives the full address |
+| `/w/<token>/<runner>` | A plugin’s page runner for a wizard that switched it on (built; from source `/api/public/wizards/<token>/runners/<runner>`) |
 
-The studio's addresses of a plugin: `/studio<path>` for its pages, `/studio/settings/<id>` for a
-settings section, `/studio/space/<group>#<id>` for a section of the space page.
+The studio’s addresses of a plugin: `/studio<path>` for its pages, `/studio/settings/<id>` for a
+settings section, `/studio/space/<group>#<id>` for a section of the space page and
+`/studio/space/<id>` for a part of it.
 
 ## Settings
 
-In the install's `.env`:
+In the install’s `.env`:
 
 | Setting | | Default |
 |---|---|---|
-| `PLUGINS_DIR` | Folders to look for plugins in, comma-separated, besides the runtime's `modules/` | Installed app: `~/.engenty/wizards/plugins`. Checkout: none |
-| `PLUGINS_WATCH` | `0`: plugins do not load again when their files change | `1` |
+| `PLUGINS_DIR` | Folders to look for plugins in, comma-separated, besides the runtime’s `modules/` | Installed app: `~/.engenty/wizards/plugins`. Checkout: none |
+| `PLUGINS_WATCH` | `0`: plugins do not load again when their files change. A runtime of engenty.ai never reloads them | `1` |
+| `PLUGINS_DEFAULT` | On engenty.ai: the ids of the plugins every tenant has, comma-separated | none |
 | `PLUGIN_JOBS` | `0`: this runtime runs no jobs (`server.every`), for one whose jobs another process runs | `1` |
 
 ## Files
@@ -321,7 +333,7 @@ In the install's `.env`:
 | `engenty.plugin.json` | The manifest: [Files and manifest](./layout.md#the-manifest) |
 | `src/plugin.ts` | The server half |
 | `migrations/*.sql` | Tables, where the server half registers the folder |
-| `ui/plugin.tsx` | The studio half's source |
+| `ui/plugin.tsx` | The studio half’s source |
 | `dist/client.js`, `dist/client.css` | The studio half, built by `node scripts/build-plugin.mjs <folder>` |
 
 ## In the repository
@@ -331,6 +343,6 @@ In the install's `.env`:
 | `packages/plugin-sdk/src/` | The types, with their comments |
 | `apps/runtime/src/plugins/` | Finding, loading, tables, events |
 | `apps/runtime/src/routes/plugins.ts` | The addresses above; `apps/runtime/src/routes/api.ts` the ones for programs |
-| `apps/web/src/plugins/` | The studio's side |
+| `apps/web/src/plugins/` | The studio’s side |
 | `scripts/build-plugin.mjs` | The build of a studio half |
 | `apps/runtime/test/plugins.test.ts` | Loading, routes, tools, tables per tenant, reloading |

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

@@ -1,23 +1,23 @@
 ---
 title: While it runs
-description: Save a file and the plugin loads again — what reloads, what survives, and how to work on a plugin.
-version: 0.4.0
+description: Save a file and the plugin loads again – what reloads, what survives, and how to work on a plugin.
+version: 0.5.0
 ---
 
-A runtime that runs alone watches its plugins. You do not restart it while you write one.
+A runtime that runs alone watches its plugins. You don’t need to restart it while you write one.
 
 ## What happens on a change
 
 | You change | What happens |
 |---|---|
-| A file of the server half | The plugin loads again: what it registered goes, its `onUnload` functions run, its files are read anew |
+| A file of the server half | The plugin loads again: what it registered is removed, its `onUnload` functions run, and its files are read again |
 | `dist/client.js`, `dist/client.css` | The open studio takes the new files in place. A page of the plugin that is open stays open |
-| A file below `ui/` | Nothing, until it is built: the change counts once `dist/` changes |
+| A file below `ui/` | Nothing happens until it is built: the change counts once `dist/` changes |
 | A new file or folder in a plugins folder | The runtime looks again: new plugins load, the others stay as they are |
-| A plugin's file or folder is removed | That plugin unloads. Its tables stay |
-| A new `.sql` file | Runs on the open tenant databases with the reload |
-| An npm dependency of the plugin | Needs a restart: Node keeps a package once it was imported |
-| The manifest's `id` | The plugin is gone under the old id and new under the new one |
+| A plugin’s file or folder is removed | That plugin unloads. Its tables stay |
+| A new `.sql` file | It runs on the open tenant databases with the reload |
+| An npm dependency of the plugin | It needs a restart: Node keeps a package once it is imported |
+| The manifest’s `id` | The plugin is gone under the old id and loads under the new one |
 
 A reload takes about as long as reading the files: well under a second.
 
@@ -25,7 +25,7 @@ A reload takes about as long as reading the files: well under a second.
 
 | | |
 |---|---|
-| Rows in the plugin's tables | Stay |
+| Rows in the plugin’s tables | Stay |
 | Variables of the module | Start again |
 | A step that is running | Keeps the tools it started with |
 | Timers, sockets, watchers | Are yours to stop: `server.onUnload`, `studio.onUnload` |
@@ -33,25 +33,26 @@ A reload takes about as long as reading the files: well under a second.
 
 ## A plugin that breaks
 
-A plugin that fails when it loads again is out until its file is mended: its tools are gone and
-its routes answer `404`. Settings → Plugins shows the error. Save a mended file and it is back.
+A plugin that fails when it loads again stays out until you fix its file: its tools are gone and
+its routes answer `404`. Settings → Plugins shows the error. Save the fixed file and the plugin
+is back.
 
 ## By hand
 
-Settings → Plugins, for owners and admins of a runtime that runs alone:
+Settings → Plugins has two buttons for owners and admins of a runtime that runs alone:
 
-| Button | Does |
+| Button | What it does |
 |---|---|
-| Reload, on a plugin | Loads that plugin again |
-| Look again | Loads every plugin again, finds new ones, drops missing ones |
+| “Reload”, the arrow on a plugin’s row | Loads that plugin again |
+| “Look again” | Loads every plugin again, finds new ones and drops missing ones |
 
-`PLUGINS_WATCH=0` in the install's `.env` turns the watching off; the buttons still work.
+`PLUGINS_WATCH=0` in the install’s `.env` turns the watching off; the buttons still work.
 
 ## Working on a plugin
 
 A loop that needs no restart, from a checkout:
 
-1. Put the plugin's folder somewhere and name its parent in `PLUGINS_DIR` (`.env.local`).
+1. Put the plugin’s folder somewhere and name its parent in `PLUGINS_DIR` (`.env.local`).
 2. Start the app:
 
    ```bash
@@ -64,12 +65,12 @@ A loop that needs no restart, from a checkout:
    node scripts/build-plugin.mjs <plugin folder> --watch
    ```
 
-4. Open the plugin's page in the studio and edit. The server half reloads on save; the page
-   updates when the build finished.
+4. Open the plugin’s page in the studio and edit. The server half reloads when you save, and
+   the page updates once the build has finished.
 
-The runtime's log names the plugins it loaded at start (`plugins: contacts, workdays`), and
-prints why one did not load.
+The runtime’s log names the plugins it loaded at start (`plugins: contacts, workdays`) and says
+why a plugin did not load.
 
 ## On engenty.ai
 
-Nothing reloads there: a new version of a plugin comes with a new start of the service.
+Nothing reloads there: a new version of a plugin arrives when the service starts again.

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

@@ -1,11 +1,11 @@
 ---
 title: Routes
-description: HTTP routes below the plugin's own address — signed in, inside the person's tenant.
-version: 0.4.3
+description: HTTP routes below the plugin's own address – signed in, inside the person's tenant.
+version: 0.5.0
 ---
 
-A plugin's routes live below `/api/studio/plugins/<id>`, and for programs with a key below
-`/api/v1/plugins/<id>`. Every request is a signed-in person's, inside that person's tenant.
+A plugin’s routes live below `/api/studio/plugins/<id>`, and for programs with a key below
+`/api/v1/plugins/<id>`. Every request is a signed-in person’s, inside that person’s tenant.
 
 ```ts
 // GET /api/studio/plugins/contacts/
@@ -50,7 +50,7 @@ server.registerHttpRoute({
 | `request.query` | The query string, as `URLSearchParams` |
 | `request.json()` | The body as JSON. An empty body is `{}` |
 | `request.user` | `{ id, tenantId, role, name, email }`: the signed-in person. `role` is `owner`, `admin` or `member` |
-| `request.path` | The address below the plugin's own |
+| `request.path` | The address below the plugin’s own |
 | `request.request` | The web `Request` as it came in: headers, a body that is not JSON |
 
 ## The answer
@@ -62,7 +62,7 @@ server.registerHttpRoute({
 | Throws an error with a `status` (400 to 599) and a `code` (a string) | That status with `{ "error": "<message>", "code": "<code>" }` |
 | Throws anything else | `500` with `{ "error": "The plugin failed.", "code": "plugin_failed" }`. The error itself is logged, not sent |
 
-Send a `code`, not a sentence for the person. The studio half says it in the person's language:
+Send a `code`, not a sentence for the person. The studio half says it in the person’s language:
 
 ```ts
 throw Object.assign(new Error("No such contact."), { status: 404, code: "no_contact" });
@@ -72,7 +72,7 @@ throw Object.assign(new Error("No such contact."), { status: 404, code: "no_cont
 
 - The studio, signed in. A request without a session gets `401` before it reaches the plugin.
 - A program with a key, at a second address: [With a key](#with-a-key).
-- Only people of a tenant that has the plugin. For any other tenant the studio's address
+- Only people of a tenant that has the plugin. For any other tenant the studio’s address
   answers `404`.
 - Not the people who run a wizard on its link, and not the outside world. For a webhook of
   another service, a plugin has [public routes](#public-routes).
@@ -80,28 +80,28 @@ throw Object.assign(new Error("No such contact."), { status: 404, code: "no_cont
 ## With a key
 
 A program that is not the studio, such as the [WordPress plugin](../../user/wordpress.md),
-calls the same routes below `/api/v1/plugins/<id>`. It signs in with an API key (on your own
-install Settings → Integrate makes one, on engenty.ai the account) or an access token of
-engenty.ai:
+calls the same routes below `/api/v1/plugins/<id>`. It signs in with an API key or with an
+access token of engenty.ai. On a runtime that runs alone, you create the key under Settings →
+Integrate; on engenty.ai, in your account:
 
 ```bash
 curl -H "Authorization: Bearer $KEY" https://wizards.example.com/api/v1/plugins/contacts/
 ```
 
-- The route runs as the key's person, inside that person's tenant: `request.user` is that
-  person, with the role. A `role: "admin"` route answers a member's key with `403`. `name` and
+- The route runs as the key’s person, inside that person’s tenant: `request.user` is that
+  person, with the role. A `role: "admin"` route answers a member’s key with `403`. `name` and
   `email` can be empty.
 - `GET` needs the scope `wizards:read`, every other method `wizards:write`. A key has every
-  scope, a token the ones the person granted. Without it: `403` with the code
+  scope, a token the ones the person granted. A call without the scope gets `403` with the code
   `insufficient_scope`.
-- A plugin the runtime has but the key's account does not answers `403` with the code `plugin`.
-  An id it does not know answers `404`.
+- A plugin that the runtime has but the key’s account does not have answers `403` with the code
+  `plugin`. An id the runtime does not know answers `404`.
 - `x-api-key: <key>` works in place of the `Authorization` header.
-- The answers and errors are the same as at the studio's address.
+- The answers and errors are the same as at the studio’s address.
 
 ## Public routes
 
-A public route answers anyone: a CMS that says a page changed, another service's webhook. Its
+A public route answers anyone: a CMS that says a page changed, another service’s webhook. Its
 address names the tenant without giving its id away; the plugin hands it out:
 
 ```ts
@@ -127,12 +127,12 @@ const address = await server.publicUrl(`/signal/${source.token}`);
   body. Keep only a hash of it.
 - The handler runs inside the tenant of the address: `server.getTenantDb()` is its database.
 - `publicUrl` gives the same address for a tenant every time.
-- A body is taken up to 4 MB. Answers and errors work as for the plugin's other routes.
+- A body is taken up to 4 MB. Answers and errors work as for the plugin’s other routes.
 - A tenant without the plugin, or a suspended one, answers `404`.
 
 ## Shared routes
 
-Some services post to one webhook for everyone: one account of the runtime's, one app. A shared
+Some services post to one webhook for everyone: one account of the runtime’s, one app. A shared
 route has one address for all tenants, and the call itself says which tenant it is for, with
 the ref the plugin handed the service before:
 
@@ -158,15 +158,19 @@ server.sharedUrl("/incoming");
 // https://…/api/public/plugins/<id>/shared/incoming
 ```
 
-- The handler runs outside any tenant: check the service's signature, then `inTenant`.
+- The handler runs outside any tenant: check the service’s signature, then call `inTenant`.
 - `inTenant(ref, work)` runs `work` inside the tenant of that ref, as a public route of the
   tenant would run. A ref no tenant has, a suspended tenant and one without the plugin throw
   `404` / `not_found`.
 - `publicRef()` is the part of `publicUrl` that names the tenant; it is the same every time.
+- A body is taken up to 4 MB, as on a public route.
+- Where the call does not carry a ref (a keyword written to a number every tenant shares),
+  [`server.claims`](./server.md#keys-across-tenants) finds it: `holder(key)` is the ref of the
+  tenant that holds the key.
 
 ## From the studio half
 
-`studio.api` calls the plugin's own routes and gives the parsed JSON:
+`studio.api` calls the plugin’s own routes and gives the parsed JSON:
 
 ```ts
 const { contacts } = await studio.api.get<{ contacts: Person[] }>("/");
@@ -177,5 +181,5 @@ See [The studio half](./studio.md#the-plugins-own-routes).
 
 ## Addresses that are taken
 
-`/api/studio/plugins/-/…` is the runtime's own part: the built files, reloading. No plugin is
+`/api/studio/plugins/-/…` is the runtime’s own part: the built files, reloading. No plugin is
 called `-`, so the two never meet.