@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,281 @@
+---
+title: The server half
+description: The function a plugin exports, what it is handed, and the rules it runs under.
+version: 0.5.0
+---
+
+The server half is a file whose default export is a function. The runtime calls it once when the
+plugin loads and hands it `wizards`. The function registers what the plugin adds.
+
+```ts
+import { definePlugin } from "@engenty/wizards/plugin";
+
+export default definePlugin((wizards) => {
+  const { server } = wizards;
+
+  server.registerMigrations("migrations");
+  server.registerHttpRoute({ method: "GET", path: "/", handler: async () => ({ ok: true }) });
+  server.registerTool({ /* … */ });
+  server.on("run.done", async (event) => { /* … */ });
+});
+```
+
+`definePlugin` only types the function. The function may be `async`.
+
+## What it is handed
+
+| | |
+|---|---|
+| `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.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 |
+|---|---|---|
+| `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 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) |
+| `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 |
+| `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:
+
+```ts
+const url = wizards.config.get("NOTIFY_URL");
+if (!url) {
+  wizards.log.warn("NOTIFY_URL is not set: nothing will be sent.");
+  return;
+}
+```
+
+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 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
+  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.
+
+## Numbers of the Manage-App
+
+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)).
+
+```ts
+const channels = await server.channels.get();
+// { number: { number: "+43…", country: "AT", kinds: ["sms", "call"], providerRef: "PN…" } | null,
+//   request: { id, country, wish, createdAt } | null,
+//   shared: [{ number, country, kinds }],
+//   allowed: true }   // false: the plan has no number of its own (Free)
+
+await server.channels.request({ userId: request.user.id, country: "AT", lang: "de" });
+await server.channels.book({ kind: "sms", quantity: segments, key: messageSid, runId });
+```
+
+- `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 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
+like any other of its calls. With a `schema` the answer is an object of that shape:
+
+```ts
+const { object } = await server.generate({
+  model: "classifier",
+  system: "You sort support mails.",
+  prompt: `Which team does this mail go to?\n\n${mail}`,
+  schema: z.object({ team: z.enum(["sales", "support", "billing"]) }),
+});
+```
+
+| Field | | Default |
+|---|---|---|
+| `prompt` | What the model is asked | required |
+| `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 |
+| `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.
+
+## Jobs
+
+```ts
+server.every("refresh", 60 * 60_000, async ({ tenantId, lastRun, signal }) => {
+  for (const source of await dueSources()) {
+    await refresh(source, signal);
+  }
+});
+```
+
+- The handler runs for every tenant that has the plugin, inside that tenant, at most once per
+  `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.
+- `PLUGIN_JOBS=0` keeps a runtime from running jobs, for one whose jobs another process runs.
+
+## The web
+
+```ts
+const page = await server.web.read("https://example.com/preise");
+// { url, status, etag, lastModified, title, description, text, links, jsonld }
+
+const res = await server.web.fetch(`${origin}/sitemap.xml`, {
+  headers: { "if-none-match": source.etag ?? "" },
+});
+```
+
+- 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
+  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
+
+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:
+
+```ts
+await db().update(store).set({ credentials: server.secrets.seal({ token }) });
+const keys = server.secrets.unseal<{ token: string }>(row.credentials);
+```
+
+`unseal` answers null for a value sealed on another install: ask for the keys again.
+
+## Documents
+
+```ts
+const { markdown, pages } = await server.documents.parse({ data, name: "preise.pdf", mime });
+```
+
+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
+
+A plugin can load again while the runtime runs. What it registered through `wizards.server` is
+taken back for it. Anything else it started, it undoes itself:
+
+```ts
+const timer = setInterval(sync, 60_000);
+server.onUnload(() => clearInterval(timer));
+```
+
+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, 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` (and `@engenty/wizards/plugin/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.

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

@@ -0,0 +1,79 @@
+---
+title: Shipping
+description: Hand a plugin to someone else, put it into a server's image, and decide which tenant has it.
+version: 0.5.0
+---
+
+## To someone’s install
+
+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:
+
+| | |
+|---|---|
+| One file | `notify.ts` |
+| A folder | The manifest, `src/`, `migrations/`, and the built `dist/`. Not `ui/`: it is the source of `dist/` |
+| 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 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
+
+Packages installed into a plugins folder count as plugins when they carry a manifest:
+
+```bash
+cd ~/.engenty/wizards/plugins
+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`.
+
+## Into a server
+
+With Docker, mount a folder and name it:
+
+```yaml
+services:
+  wizards:
+    environment:
+      PLUGINS_DIR: /plugins
+    volumes:
+      - ./plugins:/plugins
+```
+
+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
+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
+  `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/`.
+  `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`.
+
+## Which tenant has a plugin
+
+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 a plugin there.
+
+## Versions
+
+- 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.

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

@@ -0,0 +1,297 @@
+---
+title: The space
+description: Knowledge a plugin writes, a block and tools for every AI step of a space, texts in its search index, tools and cards of its assistant.
+version: 0.5.0
+---
+
+A space holds what all its wizards share: a name, its brand (logos, colours, fonts), facts, and
+Knowledge – pages, tables and files with their categories. A plugin can write Knowledge and add to
+what the space’s AI steps know, to what its search finds and to what its assistant can do. The
+runtime’s own tables call a space a project: `wizard.projectId` in a [run event](./events.md) is
+a space’s id.
+
+## Knowledge a plugin writes
+
+`server.spaceData` writes pages, tables and files into a space’s Knowledge under keys of the
+plugin’s own, with their categories. Every write is indexed: `project_search` finds it a moment
+later, filtered by its categories and checked like everything else in Knowledge. `space` is the
+space’s id.
+
+```ts
+// The source's categories, once. `proposed: true` shows them to the person to confirm first.
+await server.spaceData.putCategories({
+  space,
+  categories: [
+    { name: "Team", type: "choice", hint: "folder name" },
+    { name: "Meeting date", type: "date" },
+    { name: "Duration", type: "number", unit: "h" },
+  ],
+});
+
+// Then an item per entry. The same key again rewrites it, never doubles it.
+await server.spaceData.putPage({
+  space,
+  key: `${source.id}:2026-03-14`,
+  label: "Meeting notes",
+  title: "Weekly meeting, 14 March 2026",
+  markdown,
+  categories: { Team: "Sales", "Meeting date": "2026-03-14", Duration: 1.5 },
+  fill: true, // a model fills the categories the entry did not bring
+});
+
+// A file is read as an upload is: a page, sub-pages, a table per sheet, or a file.
+const doc = await server.spaceData.putDocument({ space, key, label, name, mime, data, fill: true });
+```
+
+| `server.spaceData.` | Does |
+|---|---|
+| `putCategories({ space, categories, proposed? })` | Adds categories, or values to known ones. Types: `choice` (with `values`, `multiple`, `ordered`), `date`, `number` (with `unit`), `text`, `boolean`. `column: { table, column }` takes a category’s values from a column of a table the plugin wrote |
+| `putPage(input)` | A page: `title`, `markdown`, `parent` (the key of a page to stand under), `original` (the file it was read from), `categories`, `fill`, `review` (why a person should look) |
+| `putTable(input)` | A table: typed `columns`, `rows` (cells by column id, they replace the rows the key had), `format: "faq"` |
+| `putFile(input)` | A file that is not a page. It is found by its name, `description` and categories; `text` is what a step reads of it |
+| `putDocument(input)` | A file, read the way an upload is. Returns what it became: `items` (pages, tables), and `review` when it was hard to read or could not be read |
+| `readPages(space, { parent? })` | The space’s own pages, whoever wrote them, with their Markdown: `{ id, title, path, parentId, markdown, origin, originKey, updatedAt }` |
+| `files(space, kind?)`, `readFile(space, id)` | The space’s files of a kind (`document`, `logo`, `asset`, `pattern`; `document` when none is named), newest first, and one file with its bytes, such as a price list someone dropped into Knowledge |
+| `list(space)` | Everything the plugin wrote, by key, with its path and `state` |
+| `remove(space, key?)` | Takes out one key, or everything the plugin wrote in the space. Returns how many items it removed |
+| `summarize(space, category?, value?)` | Writes the “Overview” of one value, or of every value with three items or more. Each costs a model call. Returns how many it wrote |
+
+- `label` is what the person knows the source as. Knowledge shows it beside the item.
+- When a person changes an item, it is theirs: the plugin’s next write returns `state: "kept"`
+  and changes nothing, and `remove` leaves it.
+- What a step reads of an item is its path: `pages/…`, `tables/…`, `files/…`.
+
+## A block for every AI step
+
+```ts
+server.registerSpaceContext({
+  block: async (space) => {
+    const titles = await pageTitles(space.id);
+    return titles.length
+      ? `# THE SPACE'S WIKI\nPages, read one with wiki_page: ${titles.join(" · ")}`
+      : null;
+  },
+  tools: [
+    {
+      name: "page",
+      description: "Reads a page of the space's wiki by its title.",
+      inputSchema: z.object({ title: z.string() }),
+      execute: async ({ title }, step) => pageOf(step.space.id, title),
+    },
+  ],
+});
+```
+
+- Every agent step of the space’s wizards gets the block in its instructions, after what the
+  space says about itself and its documents, and gets the tools with it. No step lists them.
+- `block` is called once per step. If it returns `null` or an empty text, the step gets neither
+  the block nor the tools.
+- A block is cut at 8,000 characters. A block that throws is logged, and the step runs without
+  it.
+- The tools are [tools](./tools.md) like the ones a step lists; the model sees
+  `<plugin>_<name>`. Their names and the names of the plugin’s other tools are one list.
+- A model on the device calls no tools. That is Apple Intelligence on a Mac, or on the phone a
+  run is followed on, which answers only steps that list no tools themselves. Such a step gets
+  the block without the tools.
+- `steps` says which steps get the block: `["agent"]` when left out. `"html"` stands for the
+  steps that write a document or a dashboard as HTML. They get the block without the tools,
+  after the space’s brand – a good place to say how the brand’s elements look.
+
+## The space’s brand
+
+`server.spaces.brand(space)` reads what Info & brand holds of the space’s look, for a block, a
+page or a model call in it:
+
+```ts
+const brand = await server.spaces.brand(space.id);
+// { name: "Mira Kaffee", colors: [{ name: "Primary", value: "#7a3e1d" }, …],
+//   fonts: [{ family: "Fraunces", role: "Headings", weights: [600] }, …] }
+```
+
+- The first colour is the accent. A font’s `role` is what it is for, in the person’s words.
+- It returns `null` for a space the tenant does not have. The studio half gets the same from
+  `studio.useSpace().brand`.
+
+## The search index
+
+Every agent step can search the space with `project_search`. It finds Knowledge, written by
+people and by `server.spaceData`, and the texts plugins put in themselves, outside Knowledge:
+
+```ts
+await server.index.put({
+  space: space.id,
+  key: `page:${page.id}`,
+  title: page.title,
+  text: page.markdown,
+  link: "/space/knowledge#wiki",
+});
+
+await server.index.remove(space.id, `page:${page.id}`);
+await server.index.remove(space.id); // every text of the plugin in the space
+```
+
+- Putting a key again replaces what it held.
+- A text is cut into passages. Its title is searched with it, and a hit is named by it. The test
+  search under Knowledge (“Try a search…”) shows hits as a step gets them.
+- The index searches by words and by trigrams (codes, parts of compounds). With an embedding
+  model set up, it also searches by meaning. A classifier then judges each candidate.
+- Such a text has no categories, so a search with a filter leaves it out. Write Knowledge with
+  `server.spaceData` when it should be filtered.
+- A step gets `project_search` as soon as the space has Knowledge or a plugin’s text.
+- A tenant without the plugin does not find its texts. They are deleted with the space.
+
+## Tools of the space assistant
+
+The studio’s assistant, Goose, stands on every page of the studio except the editor. Where a
+space is open and the person may change it, the assistant fills the space in from what the person
+says, a website or files. A plugin gives it tools:
+
+> Goose is still being tried out and doesn’t show in every studio yet. Where it doesn’t, nobody
+> sees the tools, cards and page hooks below.
+
+```ts
+server.registerAssistantTool({
+  name: "draft_page",
+  description: "Drafts a page of the space's wiki on a topic the person names.",
+  inputSchema: z.object({ topic: z.string() }),
+  card: true,
+  execute: async ({ topic }, turn) => {
+    turn.emit("Writing the draft …");
+    const draft = await draftPage(turn.space.id, topic, turn.signal);
+    return { title: draft.title, words: draft.words };
+  },
+});
+```
+
+| `turn.` | |
+|---|---|
+| `space` | `{ id, name }`: the space the person is filling in |
+| `tenantId`, `userId` | The tenant and the person |
+| `signal` | Aborted when the person leaves or stops the answer |
+| `emit(message)` | The line the chat shows while the assistant works |
+| `changed()` | The tool changed what the space page shows: the page draws it again |
+
+- The model sees the tool as `<plugin>_<name>`, beside the assistant’s own tools.
+- The assistant doesn’t keep a tool’s result from one message to the next. Keep what a later
+  message needs in the plugin’s tables.
+
+### A card in the chat
+
+With `card: true` the result also goes to the chat. The studio half draws it:
+
+```tsx
+studio.registerAssistantCard({
+  tool: "draft_page",
+  component: ({ data, send }) => (
+    <Card className="flex items-center gap-3 p-4">
+      <span className="flex-1 text-[0.875rem]">
+        {data.title}: {data.words} words
+      </span>
+      <Button size="sm" onClick={() => send("Publish it")}>
+        Publish it
+      </Button>
+    </Card>
+  ),
+});
+```
+
+- `tool` is the name the server half registered, without the plugin’s prefix.
+- The card stands below the assistant’s answer. Without a card for the tool, nothing shows.
+- `data` is what `execute` returned, sent as it is: keep it small.
+- `send(message)` sends a message to the assistant as if the person typed it.
+
+## Events of a space
+
+`space.created`, `space.updated`, `space.deleted`, `space.file.ready` and `space.file.removed`
+say what changed. See [Events](./events.md).
+
+## The assistant on the plugin’s own page
+
+The assistant stands on the plugin’s pages too, as on every page of the studio. A page tells it
+what to say there, and what it shows; the assistant is told what the page holds and uses the
+plugin’s assistant tools first.
+
+```tsx
+const Assistant = studio.Assistant;
+
+<Assistant
+  title="Ask about your contacts"
+  hello="I find people who ran a wizard and tidy the list."
+  placeholder="e.g. “Who ran the quote wizard last week?” …"
+  suggestions={[
+    { label: "Who came back more than once?" },
+    { label: "Remove the contacts of …", fill: true },
+  ]}
+  onChanged={() => queryClient.invalidateQueries({ queryKey: ["contacts"] })}
+/>
+```
+
+```ts
+server.registerAssistantContext({
+  block: async (space) => `THE CONTACTS ON THIS PAGE: ${await contactsText(space.id)} …`,
+});
+```
+
+- `studio.Assistant` draws nothing: place it once, anywhere in the page. `title` and `hello`
+  greet the person before the first message, and up to three `suggestions` stand under them. A
+  click sends a suggestion at once (its `message`, or the label). With `fill: true` it goes into
+  the field instead, for the person to finish.
+- `block` is called once per message, and only when the person writes from the plugin’s page. A
+  block is cut at 8,000 characters. One that throws is logged and left out.
+- Where the person may not change the space, the assistant gets neither the space’s tools nor
+  the plugins’. That is a space published from engenty wizards on a computer, or a person who
+  may not build here.
+
+### What the page shows
+
+`studio.useAssistantPage` tells the assistant what the person sees: an open item, a selection,
+a line on what the page holds, its fields. It is sent with every message, beside the page’s
+address and the trail of the top bar.
+
+```tsx
+studio.useAssistantPage({
+  open: person ? { kind: "contact", id: String(person.id), label: person.email } : undefined,
+  selection: picked.map(String),
+  summary: `${contacts.length} contacts · ${withoutName} without a name`,
+  // A page of full-height tables keeps the assistant small, at the lower right.
+  compact: true,
+});
+```
+
+- `open` is `{ kind, id?, label }`, `selection` holds the ids of what the person picked, and
+  `fields` is `{ id, label, value }[]`.
+- It takes the words of `studio.Assistant` too (`title`, `hello`, `placeholder`, `suggestions`,
+  `onChanged`): one call can do both.
+- The data may change on every render; it is read when the person sends.
+
+### Tools in the page
+
+`studio.useAssistantTool` gives the assistant a tool that runs in the browser while the page is
+shown: it filters a list, opens an item, picks a tab. The model sees it as `<plugin>_<name>`
+(a `-` in the plugin’s id becomes `_`). `run` gets the arguments and returns what the assistant
+learns. Such a tool changes what the page shows and never saves: saving stays with the server
+half’s tools.
+
+```tsx
+studio.useAssistantTool(
+  "filter_contacts",
+  {
+    description: "Shows only the contacts that match: of a wizard, by words.",
+    parameters: {
+      type: "object",
+      properties: {
+        wizard: { type: "string" },
+        query: { type: "string" },
+      },
+    },
+  },
+  ({ wizard, query }) => {
+    setFilter({ wizard: wizard as string | undefined, query: query as string | undefined });
+    return { shown: count };
+  },
+);
+```
+
+Besides a page’s tools, the assistant can open a studio page, point at an element, read what is
+on the screen, fill a field and scroll. It finds elements by their headings, labels and
+buttons. `data-assist="<id>"` on an element names it for the assistant.