wizards 0.5.0 → 0.5.2

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

@@ -1,24 +1,24 @@
 ---
 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.3.7
+version: 0.5.0
 ---
 
-A space holds what all its wizards share: a title, logos, colours, facts, and Knowledge —
-pages, tables and files with their Kategorien. A plugin writes Knowledge, adds 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.
+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 Kategorien. Every write is indexed: `project_search` finds it a moment
-later, filtered by its Kategorien and checked like everything else in Knowledge. `space` is the
-space's id.
+`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 Kategorien, once. `proposed: true` shows them to the person to take first.
+// The source's categories, once. `proposed: true` shows them to the person to confirm first.
 await server.spaceData.putCategories({
   space,
   categories: [
@@ -36,7 +36,7 @@ await server.spaceData.putPage({
   title: "Weekly meeting, 14 March 2026",
   markdown,
   categories: { Team: "Sales", "Meeting date": "2026-03-14", Duration: 1.5 },
-  fill: true, // a model fills the Kategorien the entry did not bring
+  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.
@@ -45,20 +45,20 @@ const doc = await server.spaceData.putDocument({ space, key, label, name, mime,
 
 | `server.spaceData.` | Does |
 |---|---|
-| `putCategories({ space, categories, proposed? })` | Adds Kategorien, or values to known ones. Types: `choice` (with `values`, `multiple`, `ordered`), `date`, `number` (with `unit`), `text`, `boolean`. `column: { table, column }` makes a column of a table the plugin wrote one |
+| `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 no page: found by its name, `description` and Kategorien; `text` is what a step reads of it |
-| `putDocument(input)` | A file read as an upload is. Gives what it became: `items` (pages, tables), `review` when it read badly or not at all |
-| `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 (`logo`, `asset`, `document`; `document` when none is named), newest first, and one with its bytes: a price list someone dropped into Knowledge |
+| `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 of the plugin in the space |
-| `summarize(space, category?, value?)` | Writes the Overview of values with three items or more; a model call each. Gives how many it wrote |
+| `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.
-- A person who changes an item keeps it: the plugin's next write answers `state: "kept"` and
-  changes nothing, and `remove` leaves it.
+- `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
@@ -82,40 +82,40 @@ server.registerSpaceContext({
 });
 ```
 
-- Every agent step of the space's wizards gets the block in its instructions, after what the
+- 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 asked once per step. `null` or an empty text: the step gets neither the block nor
-  the tools.
+- `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: Apple Intelligence on a Mac, or the phone a run is
-  followed on, which answers only steps that list no tools themselves. The step then gets the
-  block without the tools.
-- `steps` says which steps get it: `["agent"]` when left out. `"html"` is the steps that write a
-  document or a dashboard as HTML; they get the block without the tools, after the space's
-  brand: how the brand's elements look, say.
+  `<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
+## The space’s brand
 
-`server.spaces.brand(space)` reads what Info & brand holds of the space's look, for a block, a
+`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: "Primär", value: "#7a3e1d" }, …],
+// { 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.
-- `null` for a space the tenant does not have. The studio half gets the same as
+- 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:
+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({
@@ -131,21 +131,23 @@ 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 called by it. The test
-  search under Knowledge 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, also by meaning. A classifier then judges each candidate.
-- Such a text has no Kategorien: a search with a filter leaves it out. Write Knowledge with
+- 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 go with the space when it is
-  deleted.
+- 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 stands on every page of the studio but the editor. Where a space is open
-and may be changed, it fills it in from what the person says, a website or files. A plugin gives
-it tools:
+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({
@@ -169,9 +171,9 @@ server.registerAssistantTool({
 | `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 does not keep a tool's result from one message to the next. Keep what a later
-  message needs in the plugin's tables.
+- 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
 
@@ -193,8 +195,8 @@ studio.registerAssistantCard({
 });
 ```
 
-- `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.
+- `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.
 
@@ -203,11 +205,11 @@ studio.registerAssistantCard({
 `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 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
+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.
+plugin’s assistant tools first.
 
 ```tsx
 const Assistant = studio.Assistant;
@@ -231,16 +233,19 @@ server.registerAssistantContext({
 ```
 
 - `studio.Assistant` draws nothing: place it once, anywhere in the page. `title` and `hello`
-  greet before the first message; up to three `suggestions` stand under them. A click sends one
-  at once (its `message`, or the label); `fill: true` puts it into the field to finish first.
-- `block` is asked once per message, 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.
-- In a read-only space the assistant has none of the space's tools nor the plugins'.
+  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 goes up with every message, beside the page's
+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
@@ -253,7 +258,7 @@ studio.useAssistantPage({
 });
 ```
 
-- `open` is `{ kind, id?, label }`; `selection` the ids of what the person picked;
+- `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.
@@ -263,8 +268,9 @@ studio.useAssistantPage({
 
 `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. It changes what the page shows, never saves: saving stays with the server half's tools.
+(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(
@@ -286,6 +292,6 @@ studio.useAssistantTool(
 );
 ```
 
-Besides a page's tools the assistant can open a studio page, point at an element, read what is
+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.
+buttons. `data-assist="<id>"` on an element names it for the assistant.

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

@@ -1,11 +1,11 @@
 ---
 title: Starters
-description: Wizards a plugin brings as templates — how to register one, where it shows, and what a wizard made from it gets.
-version: 0.3.2
+description: Wizards a plugin brings as templates – how to register one, where it shows, and what a wizard made from it gets.
+version: 0.5.0
 ---
 
-A starter is a wizard a plugin brings as a template. It stands beside the marketplace's starters
-wherever a wizard is made, for the tenants that have the plugin.
+A starter is a wizard a plugin brings as a template. For the tenants that have the plugin, it
+stands beside the marketplace’s templates wherever a wizard is made.
 
 ```ts
 import { readFileSync } from "node:fs";
@@ -15,7 +15,7 @@ const read = (path: string) => readFileSync(wizards.resolvePath(path), "utf8");
 server.registerStarter({
   id: "follow-up",
   title: "Follow up a contact",
-  description: "Looks the person up and drafts a follow-up e-mail.",
+  description: "Looks the person up and drafts a follow-up email.",
   language: "en",
   definition: JSON.parse(read("starters/follow-up.json")),
   files: { "widget/card.html": read("starters/card.html") },
@@ -29,13 +29,13 @@ server.registerStarter({
 | `description` | What it makes, in one or two sentences. Shown under the title |
 | `language` | `"de"` or `"en"`, the language its texts are in. Default: `"en"` |
 | `definition` | A complete wizard definition: the JSON the studio keeps and `get_authoring_guide` describes |
-| `files` | Files of the wizard's workspace by path: widgets, sample data. A string is written as UTF-8, a `Uint8Array` as it is |
+| `files` | Files of the wizard’s workspace by path: widgets, sample data. A string is written as UTF-8, a `Uint8Array` as it is |
 
 ## Checked when it is registered
 
-The definition is read as a wizard when `registerStarter` is called. A starter that is no wizard,
-an id that is not allowed and an id registered twice throw, and the plugin does not load; the
-error names the starter:
+The definition is read as a wizard when `registerStarter` is called. A starter that is not a
+valid wizard, an id that is not allowed and an id registered twice all throw, and the plugin does
+not load. The error names the starter:
 
 ```
 Starter "follow-up": steps.2.fields: …
@@ -43,23 +43,28 @@ Starter "follow-up": steps.2.fields: …
 
 ## Where it shows
 
-The starter is known as `<plugin id>.<starter id>`: `contacts.follow-up`. A marketplace entry's id
-has no dot, so the two never meet.
+The starter is known as `<plugin id>.<starter id>`: `contacts.follow-up`. A marketplace entry’s id
+has no dot, so the two never clash.
 
 | Where | |
 |---|---|
-| New wizard in the studio | First among the templates, with the plugin's name on its card. It cannot be starred: it is always there, also without a connection |
+| New wizard in the studio | First among the gallery’s templates, and under “Similar wizards” when the wish someone types comes close to it. Its card shows the plugin’s name. It cannot be starred: it is always there, also without a connection |
 | `GET /api/studio/marketplace` | First on the first page, with `plugin: { id, name }` |
 | MCP `list_starters`, `get_starter`, `create_wizard` | Listed first with `plugin`; `starterId` takes its id |
 | `GET /api/v1/templates`, for programs with a key | First, with `plugin`; `POST /api/v1/wizards` takes its id as `starterId` |
 
 Only the tenants that have the plugin see it, by the same rule as its tools
-([Which tenant has a plugin](./shipping.md#which-tenant-has-a-plugin)). Words and filters of a search find it by its title, its description
-and the plugin's name.
+([Which tenant has a plugin](./shipping.md#which-tenant-has-a-plugin)). A search finds it by its
+title, its description and the plugin’s name.
+
+A marketplace entry can stand for a plugin’s starter. Where the tenant has that plugin, the
+entry is left out and the plugin’s own starter is listed. Where it doesn’t, the entry is marked
+Pro with the plugins it needs, and a wizard cannot be made from it.
 
 ## A wizard made from it
 
-- gets a copy of the definition and the files; later changes of the starter do not reach it.
-- keeps the starter's id in `starter`. `starterRevision` stays empty: the starter changes with
-  the plugin's version, not with a revision of its own.
+- gets a copy of the definition and the files. Later changes to the starter do not reach it.
+- keeps the starter’s id in `starter`. `starterRevision` stays empty: the starter changes with
+  the plugin’s version, not with a revision of its own.
+- is written in the starter’s `language`, whatever language the person asked for.
 - is not counted at the marketplace.

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

@@ -1,7 +1,7 @@
 ---
 title: The studio half
-description: Pages, icons in the app bar, sections of the settings and of the space page — written in React, built once, drawn inside the studio.
-version: 0.4.4
+description: Pages, icons in the app bar, sections of the settings and of the space page – written in React, built once, drawn inside the studio.
+version: 0.5.0
 ---
 
 The studio half is `ui/plugin.tsx`. Its default export is a function; the studio calls it after
@@ -84,16 +84,19 @@ export default defineStudioPlugin((studio) => {
 
 | Call | Adds |
 |---|---|
-| `studio.registerPage({ path, component, wide? })` | A page of the studio at `/studio<path>`, inside the studio's frame. `path` takes `:name` parts. `wide`: the page lays out its own columns and takes the screen's width |
+| `studio.registerPage({ path, component, wide? })` | A page of the studio at `/studio<path>`, inside the studio’s frame. `path` takes `:name` parts. `wide`: the page lays out its own columns and takes the screen’s width |
 | `studio.registerNav({ to, label, icon })` | An icon in the app bar that opens a page |
 | `studio.registerSettingsSection({ id, label, icon, component, menu? })` | A section of the settings at `/studio/settings/<id>`. `menu`: the user menu links to it directly |
-| `studio.registerSpaceSection({ id, group?, label, hint?, component })` | A section of a part of the space page at `/studio/space/<group>#<id>`, below the part's own. See [The space](#the-space) |
-| `studio.registerShareSection({ runner, component })` | A runner's own settings for a wizard (a keyword), under the share dialog's gear once the runner is on and set up. See [Runners](./runners.md#the-runners-part-of-the-share-dialog) |
-| `studio.registerShareSetup({ runner, title, component, notice? })` | What "Einrichten" in the runner's row opens: a view inside the share dialog, with its buttons at the dialog's foot, and a banner of the runner's news. See [Runners](./runners.md#setting-up-inside-the-dialog) |
-| `studio.registerAssistantCard({ tool, component })` | A card in the assistant's chat for what a tool of the server half returned. See [The space](./space.md#a-card-in-the-chat) |
+| `studio.registerSpaceSection({ id, group?, label, hint?, component })` | A section of a part of the space page at `/studio/space/<group>#<id>`, below the part’s own. See [The space](#the-space) |
+| `studio.registerSpacePart({ id, label, icon, after?, component })` | A part of the space page of the plugin’s own, at `/studio/space/<id>`. See [A part of the plugin’s own](#a-part-of-the-plugins-own) |
+| `studio.registerShareSection({ runner, component })` | A runner’s own settings for a wizard (a keyword), under the share dialog’s gear once the runner is on and set up. See [Runners](./runners.md#the-runners-part-of-the-share-dialog) |
+| `studio.registerShareSetup({ runner, title, component, notice? })` | What “Set up” in the runner’s row opens: a view inside the share dialog, with its buttons at the dialog’s foot, and a banner of the runner’s news. See [Runners](./runners.md#setting-up-inside-the-dialog) |
+| `studio.registerAssistantCard({ tool, component })` | A card in the assistant’s chat for what a tool of the server half returned. See [The space](./space.md#a-card-in-the-chat) |
 
-- The studio's own addresses are taken: `/new`, `/edit`, `/settings`, `/space`, `/setup`,
+- The studio’s own addresses are taken: `/new`, `/edit`, `/settings`, `/space`, `/setup`,
   `/sign-in`.
+- The settings’ own sections are taken as ids: `account`, `team`, `connectors`, `models`,
+  `integrate` and `plugins`.
 - `label` is a function, since the language can change while the studio is open.
 - `icon` is a component that takes `className`: any icon of `lucide-react`.
 
@@ -125,11 +128,11 @@ space page, behind the house icon (Space) in the app bar, shows them in four par
 | Part | `group` | Holds |
 |---|---|---|
 | Info & brand | `info` | Basics, Facts, Logos, Colours, Brand assets |
-| Knowledge | `knowledge` | Documents, pages, tables and files with their Kategorien: what every AI step looks things up in |
+| Knowledge | `knowledge` | Documents, pages, tables and files with their categories: what every AI step looks things up in |
 | Data | `data` | What the wizards keep |
 | Results | `results` | The runs that reached their result |
 
-A plugin adds a section to one of them, below the part's own:
+A plugin adds a section to one of them, below the part’s own:
 
 ```tsx
 function ContactsOfSpace() {
@@ -152,26 +155,27 @@ studio.registerSpaceSection({
 ```
 
 - `group` is the part; without one the section stands under Knowledge.
-- The studio draws the heading and the hint above the section, as it does for the space's own,
-  and lists the section in the part's menu under the plugin's name. The component draws the
+- The studio draws the heading and the hint above the section, as it does for the space’s own,
+  and lists the section in the part’s menu under the plugin’s name. The component draws the
   rest, usually a `Card`.
-- `id` is the section's anchor: `/studio/space/data#contacts` opens the page there, and so does
+- `id` is the section’s anchor: `/studio/space/data#contacts` opens the page there, and so does
   `/studio/space#contacts`. In Knowledge a section is a page of its own:
   `/studio/space/knowledge?show=s:<id>`, where `#<id>` leads too. Ids are unique on the whole
-  page; the space's own are taken: `base`, `facts`, `logos`, `colors`, `typography`, `assets`,
+  page; the space’s own are taken: `base`, `facts`, `logos`, `colors`, `typography`, `assets`,
   `documents`.
 - `studio.useSpace()` is a hook: `{ id, name, readOnly, brand }`, or `null` while there is none.
   A component that calls it draws again when the person picks another space, or changes its
-  brand. `readOnly`: the space came from a local install, or nothing is built on this runtime;
-  show it, change nothing. `brand` is what Info & brand holds of the look: `name`, `colors`
-  (`{ name, value }`, the first is the accent) and `fonts` (`{ family, role, weights }`).
+  brand. `readOnly`: the space is edited in engenty wizards on a computer and only shown here,
+  or nothing is built on this runtime. Show it, but change nothing. `brand` is what Info & brand
+  holds of the look: `name`, `colors` (`{ name, value }`, the first is the accent) and `fonts`
+  (`{ family, role, weights }`).
 - Every wizard belongs to a space: a [run event](./events.md) names it as
-  `wizard.projectId`. Keep it with what the plugin stores to show a space's part of it.
+  `wizard.projectId`. Keep it with what the plugin stores to show a space’s part of it.
 
-### A part of the plugin's own
+### A part of the plugin’s own
 
 A plugin whose subject is as big as one of the parts adds a part of its own: an entry in the
-parts' menu, with a page at `/studio/space/<id>` that the plugin draws whole. The part's menu
+parts’ menu, with a page at `/studio/space/<id>` that the plugin draws whole. The part’s menu
 lists what the page holds; `studio.useSpaceMenu` fills it while the page is drawn.
 
 ```tsx
@@ -195,16 +199,16 @@ studio.registerSpacePart({
 });
 ```
 
-- `id` is the address: `/studio/space/library`. The parts' own (`info`, `knowledge`, `data`,
+- `id` is the address: `/studio/space/library`. The parts’ own (`info`, `knowledge`, `data`,
   `results`) are taken.
 - `after` is the part it follows in the menu: `info`, `knowledge` or `data` (default).
 - Each entry of `useSpaceMenu` jumps to the element with its `id` in what the part draws, and
-  the menu marks the one in view. `Anchor` and `Section` draw them as the space's own parts do.
-- The component is drawn again for another space: keep the space's data under its id.
+  the menu marks the one in view. `Anchor` and `Section` draw them as the space’s own parts do.
+- The component is drawn again for another space: keep the space’s data under its id.
 
 ## Words in two languages
 
-The studio speaks German and English. `studio.i18n.register` takes the plugin's words and gives
+The studio speaks German and English. `studio.i18n.register` takes the plugin’s words and gives
 the function that reads them in the language in effect:
 
 ```ts
@@ -216,12 +220,12 @@ const t = studio.i18n.register({
 t("count", { n: 12 });
 ```
 
-- `de` is the source: a key missing in `en` shows the German.
+- `de` is the source: a key missing in `en` shows the German, so give every key in both.
 - `{name}` in a text is filled from the second argument.
 - `studio.i18n.lang()` is `"de"` or `"en"`, for dates and numbers:
   `new Date(at).toLocaleString(studio.i18n.lang())`.
 
-## The plugin's own routes
+## The plugin’s own routes
 
 `studio.api` calls the routes the server half registered, signed in as the person:
 
@@ -251,8 +255,8 @@ route.
 
 ## Where the page stands
 
-The top bar shows a trail after the space's name. `studio.useCrumbs` is a hook that sets it
-while the page is shown, in place of a heading of the page's own:
+The top bar shows a trail after the space’s name. `studio.useCrumbs` is a hook that sets it
+while the page is shown, in place of a heading of the page’s own:
 
 ```tsx
 studio.useCrumbs([{ label: t("title"), to: "/contacts" }, { label: person.name ?? person.email }]);
@@ -261,16 +265,54 @@ studio.useCrumbs([{ label: t("title"), to: "/contacts" }, { label: person.name ?
 - Each step is `{ label, to? }`; the last one is the page itself. A phone does not show the trail.
 - The assistant names the page by its trail.
 
+## A page with a menu
+
+A page with parts of its own puts its menu where the studio’s own pages put theirs. `MenuPage`
+from `@engenty-wizards/web/ui` draws the menu in the studio’s sidebar while that is open, and at
+the page’s left otherwise, so there is only ever one menu at the left. `PageMenu` draws the menu
+as the settings do: a list with one level below it, and tabs on a phone.
+
+```tsx
+import { MenuPage, PageMenu } from "@engenty-wizards/web/ui";
+import { useParams } from "react-router";
+
+function ContactsPage() {
+  const { tab = "all" } = useParams();
+  return (
+    <MenuPage
+      menu={
+        <PageMenu
+          title={t("title")}
+          current={tab}
+          entries={[
+            { id: "all", label: t("all"), to: "/contacts/all" },
+            { id: "new", label: t("new"), to: "/contacts/new" },
+          ]}
+        />
+      }
+    >
+      <ContactList tab={tab} />
+    </MenuPage>
+  );
+}
+```
+
+- An entry is `{ id, label, icon?, to, entries? }`; `entries` is the level below.
+- `current` is the id of the entry shown, at either level.
+
 ## The assistant
 
-The studio's assistant stands on a plugin's pages too. `studio.Assistant`,
+The studio’s assistant stands on a plugin’s pages too. `studio.Assistant`,
 `studio.useAssistantPage` and `studio.useAssistantTool` tell it what to say there, what the page
 shows and what it may do in it. See [The space](./space.md#the-assistant-on-the-plugins-own-page).
 
+For now the studio shows its assistant only where it is switched on, and it is off by default.
+While it is off, these calls do no harm and nobody sees what they say.
+
 ## Build it
 
 The studio half is built to two files, `dist/client.js` and `dist/client.css`. The build needs
-a checkout of the repository, since it uses the studio's own tools:
+a checkout of the repository, since it uses the studio’s own tools:
 
 ```bash
 node scripts/build-plugin.mjs <plugin folder>
@@ -280,7 +322,7 @@ node scripts/build-plugin.mjs <plugin folder>
 node scripts/build-plugin.mjs <plugin folder> --watch
 ```
 
-The plugin's folder may be anywhere, also outside the checkout. With `--watch` the files are
+The plugin’s folder may be anywhere, also outside the checkout. With `--watch` the files are
 built again on every save, and an open studio takes them in place.
 
 Ship `dist/` with the plugin: an install without a checkout cannot build it.
@@ -296,11 +338,11 @@ there is one React and one router on the page:
 | `react-dom` | `createPortal`, `flushSync` |
 | `react-router` | `Link`, `NavLink`, `Navigate`, `useNavigate`, `useParams`, `useLocation`, `useSearchParams` |
 | `@tanstack/react-query` | `useQuery`, `useMutation`, `useQueryClient` |
-| `@engenty-wizards/web/ui` | The studio's components, see [Styles and components](./styling.md) |
+| `@engenty-wizards/web/ui` | The studio’s components, see [Styles and components](./styling.md) |
 | `@engenty-wizards/plugin-sdk/studio` | `defineStudioPlugin` and the types |
 
-Everything else a plugin imports is bundled into `client.js`. A package the plugin's folder
-does not have, such as `lucide-react`, comes from the studio's.
+Everything else a plugin imports is bundled into `client.js`. A package the plugin’s folder
+does not have, such as `lucide-react`, comes from the studio’s.
 
 ## Undo on reload
 
@@ -314,7 +356,8 @@ studio.onUnload(() => clearInterval(timer));
 
 ## When it fails
 
-- A studio half that throws while it loads registers nothing. Settings → Plugins says "The
-  studio half did not load" with the reason. The server half keeps working.
-- A page or section that throws while it draws shows "This part of a plugin crashed" in its
+- A studio half that throws while it loads registers nothing. Settings → Plugins says “The
+  studio part didn’t load. Check the plugin and reload” with the reason. The server half keeps
+  working.
+- A page or section that throws while it draws shows “This part of a plugin crashed.” in its
   place. The rest of the studio stays up.