wizards 0.4.7 → 0.5.1

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

@@ -1,17 +1,17 @@
 ---
 title: Styles and components
 description: The studio's components, Tailwind against the studio's theme, and why a plugin's styles never leak.
-version: 0.3.7
+version: 0.5.0
 ---
 
-A plugin's page should look like the studio. Two things make that easy: the studio's components
+A plugin’s page should look like the studio. Two things make that easy: the studio’s components
 and its theme.
 
 ## Components
 
 `@engenty-wizards/web/ui` is what the studio itself is drawn with:
 
-| Component | For | Props beside the element's own |
+| Component | For | Props beside the element’s own |
 |---|---|---|
 | `Button` | An action | `variant`: `primary` (default), `secondary`, `ghost`, `quiet`, `danger` · `size`: `sm`, `md`, `lg` · `busy` |
 | `IconButton` | An action that is only an icon | `label`: its name for screen readers and the tooltip |
@@ -20,26 +20,28 @@ and its theme.
 | `Segmented` | One or several of a few | `value`, `onChange`, `options: string[]`, `multi`, `disabled` (options shown but not to be picked) |
 | `Tabs` | A row of tabs; the panels are yours | `value`, `onChange`, `options: { id, label }[]`, `label` (for screen readers) |
 | `Switch` | On or off | `checked`, `onChange(checked)`, `label`, `disabled` |
-| `Swatch` | A colour | The native colour input's |
-| `Label` | A field's label | `hint`, `required` |
+| `Swatch` | A colour | The native colour input’s |
+| `Label` | A field’s label | `hint`, `required` |
 | `Card` | A surface | |
 | `Chip` | A state in a word | `tone`: `neutral` (default), `live`, `warn`, `ember` · `icon` (in place of the live dot) · `title` (on hover) |
-| `DatePicker` | A date from a month | `value` ("YYYY-MM-DD" or ""), `onChange`, `min`, `max`, `clearable` |
+| `DatePicker` | A date from a month | `value` (“YYYY-MM-DD” or “”), `onChange`, `min`, `max`, `clearable` |
 | `DateRangePicker` | A day or a period in one month: the first click is the start, the second the end | `from`, `to`, `onChange({ from, to })`, `min`, `max` |
-| `TimePicker` | A time of day from an hour and a minute column; arrow keys on the field move it by `step` | `value` ("HH:MM" or ""), `onChange`, `step` (minutes, default 5), `compact` (narrow, no clock) |
-| `PageMenu` | A page's own menu: a list at the side with one level below that slides in, tabs on a phone | `title`, `entries` ({ id, label, icon?, to, entries? }), `current`, `footer` |
+| `TimePicker` | A time of day from an hour and a minute column; arrow keys on the field move it by `step` | `value` (“HH:MM” or “”), `onChange`, `step` (minutes, default 5), `compact` (narrow, no clock) |
+| `PageMenu` | A page’s own menu: a list at the side with one level below that slides in, tabs on a phone | `title`, `entries` ({ id, label, icon?, to, entries? }), `current`, `footer` |
+| `MenuPage` | A page with a menu of its own: the menu stands at the page’s left, or in the studio’s sidebar while that is open, so there is only ever one menu at the left | `menu` (a `PageMenu`, or any), `children` (the page) |
 | `Composer` | The field a message is written in: text, dictation, files, send | `onSend(text, files)` (false keeps the draft), `placeholder`, `disabled`, `attach`, `floating` |
 | `Dialog` | A modal; on a phone it fills the screen | `open`, `onClose`, `title`, `wide` (`true`, or `"page"` for a document), `height="tall"` (for tabs, folds or lists: its height does not jump), `bare` (the children are the panel) |
 | `Spinner`, `Empty` | Loading, and nothing there yet | |
 | `LinkedText` | A sentence with its web addresses as links, named by their host | `text` |
+| `QrCode` | A QR code of a text, such as a link or a `tel:` number, as the share dialog draws it | `text`, `label` (for screen readers) |
 | `cn(...)` | Joins class names, skipping what is false | |
-| `dateText(date, withWeekday?)` | A "YYYY-MM-DD" date in the studio's language: "Wed 14 Oct 2026" | |
+| `dateText(date, withWeekday?)` | A “YYYY-MM-DD” date in the studio’s language: “Wed 14 Oct 2026” | |
 | `Anchor`, `Section` | A section of the space page and the spot the menu jumps to: the heading and its hint above the card | `id` on the anchor · `title`, `hint`, `save` (how the last save went), `action` (beside the heading), `plain` (the content draws its own cards) |
-| `InlineText` | Text edited where it stands, without a field's frame | `value`, `onChange`, `placeholder`, `label`, `maxLength`, `fit` (as wide as its text) |
-| `AddMenu` | The "Add" menu of a section's heading | `entries: { label, icon, onPick }[]` |
-| `AddRow` | A quiet "+ …" row at the end of a list | `label`, `onClick` |
-| `RuleRows`, `useRuleRows(saved)` | Rules as rows, each with its sign (bullet, do, don't, to check, important, numbered) | `rules` (what the hook gives), `placeholder`, `readOnly` |
-| `useAutosave(value, save)` | Saves a value a moment after it last changed; gives the state for a section's `save` | |
+| `InlineText` | Text edited where it stands, without a field’s frame | `value`, `onChange`, `placeholder`, `label`, `maxLength`, `fit` (as wide as its text) |
+| `AddMenu` | The “Add” menu of a section’s heading | `entries: { label, icon, onPick }[]` |
+| `AddRow` | A quiet “+ …” row at the end of a list | `label`, `onClick` |
+| `RuleRows`, `useRuleRows(saved)` | Rules as rows, each with its sign (bullet, do, don’t, to check, important, numbered) | `rules` (what the hook gives), `placeholder`, `readOnly` |
+| `useAutosave(value, save)` | Saves a value a moment after it last changed; gives the state for a section’s `save` | |
 | `newId()` | A short id for something new | |
 
 ```tsx
@@ -57,17 +59,17 @@ import { Button, Card, Chip, Label, Input } from "@engenty-wizards/web/ui";
 
 Icons are from `lucide-react`.
 
-Most of these components live in the runner package (`@engenty-wizards/runner`), so a wizard's
-run page looks like the studio. Import them from `@engenty-wizards/web/ui` all the same: that
-is the import the studio shares. `@engenty-wizards/runner` is not shared and would be bundled
-into `client.js`.
+Most of these components live in the runner package (`@engenty-wizards/runner`), so a wizard’s
+run page looks like the studio. Import them from `@engenty-wizards/web/ui` all the same: that is
+the import the studio shares. `@engenty-wizards/runner` is not shared, so the build would bundle
+it into `client.js`.
 
 ## Tailwind
 
 A plugin writes Tailwind classes, as the studio does. The build collects the classes the
-plugin's files use into `dist/client.css`.
+plugin’s files use into `dist/client.css`.
 
-The theme's names are the studio's:
+The theme’s names are the studio’s:
 
 | | Names |
 |---|---|
@@ -77,33 +79,34 @@ The theme's names are the studio's:
 | The accent | `ember`, `ember-strong`, `ember-tint`; `primary`, `primary-foreground` |
 | States | `moss` and `moss-tint` (good), `amber` and `amber-tint` (attention), `rose` and `rose-tint` (danger), `cobalt` and `cobalt-tint` (information) |
 | Type | `font-sans`, `font-display` (headings), `font-mono` |
-| Corners | `rounded-sm` to `rounded-3xl`, from the theme's radius |
+| Corners | `rounded-sm` to `rounded-3xl`, from the theme’s radius |
 | Shadows | `shadow-soft`, `shadow-elevated`, `shadow-overlay` |
-| Variants | `dark:` and `coarse:` (a finger, not a mouse) beside Tailwind's own |
+| Variants | `dark:` and `coarse:` (a finger, not a mouse) beside Tailwind’s own |
 
 The full list is
 [packages/runner/src/theme.css](https://github.com/engenty/wizards/blob/main/packages/runner/src/theme.css):
-the studio and a wizard's run page share it.
+the studio and a wizard’s run page share it.
 
 ## Rules
 
-- **Colours come from the names.** Dark is derived from the theme's values, not a fixed
-  palette. A literal colour (`#1a1a1a`, `text-gray-700`) breaks in the other theme.
-- **Check both themes.** The user menu switches between light and dark.
-- **Touch targets.** `coarse:min-h-11` gives a control the 44 px a finger needs. The studio's
+- **Colours come from the names.** The dark theme is derived from the theme’s values, not from a
+  fixed palette. A literal colour (`#1a1a1a`, `text-gray-700`) breaks in the other theme.
+- **Check both themes.** Dark is the studio’s default. The user menu and the app bar’s own menu
+  switch between light, dark and the system’s.
+- **Touch targets.** `coarse:min-h-11` gives a control the 44 px a finger needs. The studio’s
   components do that themselves.
-- **Do not style outside your own part.** It would not work anyway: see below.
+- **Don’t style outside your own part.** It would not work anyway: see below.
 
-## Why a plugin's styles never leak
+## Why a plugin’s styles never leak
 
 `client.css` is built so that it cannot change how the studio looks:
 
 - Every rule applies only inside what the plugin draws. The studio wraps each page, section,
-  app bar icon, part of the share dialog and assistant card of a plugin in an element with
-  `data-plugin="<id>"`, and every rule of `client.css` is nested below that.
-- The rules sit in a layer above the studio's utilities, so inside the plugin's part the
-  plugin's stylesheet decides.
-- The theme is used by reference: `client.css` carries the names' uses, none of the variables
+  part of the space page, app bar icon, part of the share dialog and assistant card of a plugin
+  in an element with `data-plugin="<id>"`, and every rule of `client.css` is nested below that.
+- The rules sit in a layer above the studio’s utilities, so inside the plugin’s part the
+  plugin’s stylesheet decides.
+- The theme is used by reference: `client.css` carries the names’ uses, none of the variables
   and no resets.
 
 ## Your own CSS
@@ -114,13 +117,13 @@ A stylesheet imported in `ui/plugin.tsx` lands in `client.css` as it is:
 import "./contacts.css";
 ```
 
-It is not nested for you. Begin its class names with the plugin's id (`.contacts-chart`) and use
-the theme's variables for colours: `var(--ink-2)`, `var(--paper-2)`, `var(--ember)`.
+The build doesn’t nest it for you. Begin its class names with the plugin’s id
+(`.contacts-chart`) and use the theme’s variables for colours: `var(--ink-2)`, `var(--paper-2)`,
+`var(--ember)`.
 
 ## The theme is a contract
 
-A plugin is built against the names of the theme at the time of its build. A name that is
-renamed or removed in a later release breaks plugins built before, without an error: the class
-is simply not there. Whoever changes `theme.css` treats its names as a contract for that reason.
-If you build against a name a release added, say in your plugin's description which release it
-needs.
+A plugin is built against the names the theme has at the time of its build. If a later release
+renames or removes a name, plugins built before break without an error: the class is simply not
+there. That is why whoever changes `theme.css` treats its names as a contract. If you build
+against a name a release added, say in your plugin’s description which release it needs.

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

@@ -1,11 +1,11 @@
 ---
 title: Tables
-description: A plugin's own tables in every tenant's database — SQL files that run once, and Drizzle to read and write.
-version: 0.3.2
+description: A plugin's own tables in every tenant's database – SQL files that run once, and Drizzle to read and write.
+version: 0.5.0
 ---
 
-Every tenant has a database of its own (libSQL, the SQLite dialect). A plugin's tables are made
-in each of them, from `.sql` files the plugin brings.
+Every tenant has a database of its own (libSQL, the SQLite dialect). The runtime makes a plugin’s
+tables in each of them, from `.sql` files the plugin brings.
 
 ## 1. The table, as SQL
 
@@ -79,13 +79,13 @@ there is no tenant.
 | When | A database gets the files when it opens. The open ones get them when the plugin loads, also when it loads again with a new file |
 | Never back | Nothing is taken back. Unloading or removing a plugin leaves its tables and rows |
 
-A file that fails is logged with the plugin's id and the file's name, and the files after it,
-other plugins' included, wait for that database until it is mended. The tenant's database
-still opens.
+A file that fails is logged with the plugin’s id and the file’s name. The files after it, other
+plugins’ included, wait for that database until the file is fixed. The tenant’s database still
+opens.
 
 ## Rules
 
-- **Begin table names with the plugin's id**: `contacts_person`. All plugins and the runtime
+- **Begin table names with the plugin’s id**: `contacts_person`. All plugins and the runtime
   share the database. A `-` in the id becomes `_`.
 - **Never change a file that ran.** It will not run again. Add a new file:
 
@@ -93,12 +93,12 @@ still opens.
   ALTER TABLE contacts_person ADD COLUMN phone TEXT;
   ```
 
-- **Do not touch the runtime's own tables** in a migration. Their shape changes with releases.
+- **Do not touch the runtime’s own tables** in a migration. Their shape changes with releases.
 - **Dates** are integers in milliseconds (`mode: "timestamp_ms"`); they leave a route as ISO
   strings.
 
-## The runtime's own data
+## The runtime’s own data
 
-`getTenantDb()` reaches the whole tenant database, the runtime's tables included. They are not
+`getTenantDb()` reaches the whole tenant database, the runtime’s tables included. They are not
 a public interface: a release can rename a column. A plugin that must know about runs listens
 to [run events](./events.md) and keeps what it needs in its own table.

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

@@ -1,18 +1,18 @@
 ---
 title: Tools
-description: A tool an AI step can call — how to register it, how a wizard lists it, and what the model sees.
-version: 0.3.2
+description: A tool an AI step can call – how to register it, how a wizard lists it, and what the model sees.
+version: 0.5.0
 ---
 
 A tool is a function an AI step may call while it works. The model decides when, from the
-tool's description.
+tool’s description.
 
 ```ts
 server.registerTool({
   name: "lookup",
   title: "Contacts",
   description:
-    "Looks a person up by e-mail among the people who ran a wizard of this project before.",
+    "Looks a person up by email among the people who ran a wizard of this space before.",
   inputSchema: z.object({ email: z.string().email() }),
   execute: async ({ email }) => {
     const [found] = await db()
@@ -36,8 +36,8 @@ server.registerTool({
 
 | Where | The tool is called |
 |---|---|
-| A step's `tools` in a wizard | `contacts.lookup`: `<plugin id>.<tool name>` |
-| The model | `contacts_lookup`. A `-` in the plugin's id becomes `_`: `run-log.recent` is `run_log_recent` |
+| A step’s `tools` in a wizard | `contacts.lookup`: `<plugin id>.<tool name>` |
+| The model | `contacts_lookup`. A `-` in the plugin’s id becomes `_`: `run-log.recent` is `run_log_recent` |
 | The editor | Its `title` |
 
 ## What `execute` knows
@@ -48,10 +48,10 @@ The second argument is the step that calls the tool:
 |---|---|
 | `step.runId`, `step.stepId` | The run and the step |
 | `step.tenantId` | The tenant |
-| `step.space` | `{ id, name }`: the space of the step's wizard |
+| `step.space` | `{ id, name }`: the space of the step’s wizard |
 | `step.project` | The same as `step.space`, by its older name |
 | `step.wizard` | `{ id, title }` |
-| `step.mode` | `"test"` for a test run from the studio, else `"live"`. Keep what a test makes apart: a booking, a message to someone outside |
+| `step.mode` | `"test"` for a test run from the studio, else `"live"`. Keep what a test run makes apart, such as a booking or a message to someone outside |
 | `step.signal` | Aborted when the run is cancelled. Pass it to `fetch` |
 | `step.emit(message)` | Tells the person what the step is doing right now |
 
@@ -68,8 +68,8 @@ execute: async ({ url }, step) => {
 ## Errors
 
 An error thrown in `execute` does not fail the step. The model gets `{ "error": "<message>" }`
-as the tool's result, with the first 400 characters of the message, and can try again or work
-around it. Throw an error whose message says what was wrong with the input.
+as the tool’s result, with the first 400 characters of the message, and can try again or work
+around it. Throw errors whose message says what was wrong with the input.
 
 ## In a wizard
 
@@ -79,19 +79,20 @@ A step lists the tool beside the built-in ones:
 "tools": ["web_search", "contacts.lookup"]
 ```
 
-- The editor offers the tools of the tenant's plugins in every AI step.
+- The editor offers the tools of the tenant’s plugins in every AI step.
 - The assistant and the MCP authoring guide list them with their descriptions.
-- A draft whose step lists a tool in `tools` that this tenant does not have shows an issue.
-- A run fails at the step that names one. A wizard that uses a plugin's tool runs only where
-  that plugin is installed: think of that before you publish a wizard to the cloud or export it.
-- The model has to call tools. Apple Intelligence on a Mac calls none: a step whose class it
+- A draft with a step that lists a tool this tenant does not have shows an issue.
+- A run fails at the step that names such a tool, with “This step needs the tool “…”. The
+  plugin “…” isn’t installed here.” A wizard that uses a plugin’s tool runs only where that
+  plugin is installed. Keep that in mind before you publish a wizard to the cloud or export it.
+- The model has to call the tools. Apple Intelligence on a Mac calls none: a step whose class it
   answers (Classifier, Standard) runs from its prompt alone. A step that needs the tool runs on
-  High, or a [call without a model](#called-without-a-model) does it.
+  High, or a [call without a model](#called-without-a-model) does the job.
 
 ### Called without a model
 
-Where a step only fetches data and hands it on unchanged, it calls the tool itself: no model
-picks the tool, and none copies its answer.
+Where a step only fetches data and hands it on unchanged, it can call the tool itself: no model
+picks the tool, and no model copies its answer.
 
 ```json
 {
@@ -112,26 +113,26 @@ picks the tool, and none copies its answer.
 }
 ```
 
-- The tool's answer is the step's json output, as it is. An answer that is not an object (a
+- The tool’s answer is the step’s json output, as it is. An answer that is not an object (a
   list, a text) is kept as `{ "result": … }`. `output.fields` name the keys later steps read,
   so the editor and the checks know them.
-- String inputs are templates. A filled-in number or `true`/`false` is passed as one; an
-  empty one is left out. The input is checked against the tool's schema.
-- What the tool throws, or an answer that is only `{ "error": … }`, is the step's error. A tool
+- String inputs are templates. A template that fills in to a number or to `true`/`false` is
+  passed as one, and an empty one is left out. The input is checked against the tool’s schema.
+- What the tool throws, or an answer that is only `{ "error": … }`, is the step’s error. A tool
   this tenant does not have fails the step too.
 - It costs no credits and answers as fast as the tool: the free times of a calendar in under a
   second instead of half a minute.
 
 ## While a step runs
 
-A step that is running keeps the tools it started with. A plugin that loads again changes the
-tools of the next step.
+A step that is running keeps the tools it started with. When a plugin loads again, the change
+reaches the next step.
 
 ## Write a good tool
 
 - One job per tool. Two small tools are easier for a model to choose between than one with a
   `mode` field.
-- Describe the result as well as the input: "returns the working days as a number".
+- Describe the result as well as the input: “returns the working days as a number”.
 - Return data, not prose. The step writes the sentences.
 - Bound what it returns: a `limit` with a maximum, the newest 50 rows.
 - A tool that changes something outside says so in its description. There is no

package/apps/runtime/dist/docs/dev/wizard-format.md

@@ -1,12 +1,12 @@
 ---
 title: The wizard format
 description: A wizard as JSON and as a .wizard file, its JSON Schema, and checking it with wizards validate.
-version: 0.3.2
+version: 0.5.0
 ---
 
-A wizard is one JSON document, its **definition**. The studio exports it as a `.wizard` file,
-and imports one back. Both can be written by hand or by a tool, checked in your editor against a
-JSON Schema, and checked completely with `wizards validate`.
+A wizard is one JSON document, its **definition**. The studio exports it as a `.wizard` file
+and imports one back. You can write either by hand or with a tool, check it in your editor
+against a JSON Schema, and check it completely with `wizards validate`.
 
 The code that defines the format and checks it is also under the
 [MIT licence](https://github.com/engenty/wizards/blob/main/packages/shared/LICENSE-MIT), so any
@@ -21,25 +21,31 @@ tool may read and write wizards.
   "title": "Create an invoice",
   "description": "A finished invoice from a few details.",
   "avatar": "round",
+  "lang": "en",
   "steps": [ … ]
 }
 ```
 
-`steps` run top to bottom, and the last one is always a `result` step. The step types and their
-fields are in the schema below. The studio's MCP tool `get_authoring_guide` explains them with a
-complete example.
+`steps` run from top to bottom, and the last one is always a `result` step. The schema below
+lists the step types and their fields. The studio’s MCP tool `get_authoring_guide` explains them
+with a complete example.
 
-`version` is the definition's version. It changes only with a breaking change; the schemas of
+`lang` is the language the wizard speaks to people: `de` or `en`. It sets the runner’s own words
+and how numbers and dates are written. Without it, the language is read from the wizard’s own
+words, and English is the default where they are not clearly German.
+
+`version` is the definition’s version. It changes only with a breaking change; the schemas of
 each version stay online in their own folder (`/schema/v1/`, `/schema/v2/`, …).
 
 ## The `.wizard` file
 
-A zip with two things in it:
+The file is a zip with two things in it:
 
 | Path | What it holds |
 |---|---|
-| `wizard.json` | The manifest: the definition, plus what it needs from its project |
-| `files/…` | The wizard's workspace: widget pages, templates, images. At most 200 files and 25 MB |
+| `wizard.json` | The manifest: the definition, plus what the wizard needs from its space |
+| `files/…` | The wizard’s workspace: widget pages, templates, images. At most 200 files and 25 MB |
+| `files/knowledge/…` | Only when the export was asked for it: the space’s Knowledge pages as Markdown files, one per page, with its title in front. A website runs the wizard with them, without the space |
 
 ```json
 {
@@ -52,11 +58,16 @@ A zip with two things in it:
 }
 ```
 
-`connectors` and `mcpServers` name what the wizard's steps use from its project, without
-addresses or credentials. A project that lacks one is told so on import.
+`connectors` and `mcpServers` (the space’s connected systems) name what the wizard’s steps use
+from its space, without addresses or credentials. When the space you import into lacks one, the
+import says so.
+
+`knowledge` (`{ "pages": 12, "truncated": false }`) is there when the export took the space’s
+pages along. It says how many there are and whether the cap of about 2 MB left some out. The
+share dialog’s website package does this with “Take the knowledge along”.
 
 The import also takes a `wizard.json` on its own, or a definition on its own.
-The file's media type is `application/vnd.engenty.wizard+zip`.
+The file’s media type is `application/vnd.engenty.wizard+zip`.
 
 ## JSON Schema
 
@@ -66,14 +77,14 @@ The file's media type is `application/vnd.engenty.wizard+zip`.
 | `wizard.json` in a package | [`https://engenty.ai/schema/v1/wizard-package.json`](https://engenty.ai/schema/v1/wizard-package.json) |
 
 Put the address under `"$schema"`, and editors such as VS Code complete keys and mark mistakes
-as you type. The studio's export writes it into every `wizard.json`.
+as you type. The studio’s export writes it into every `wizard.json`.
 
 The schemas are written from the code that reads wizards, so they match it. They are stricter
 in one way: a key the app does not know is an error. The app would drop such a key without a
 word.
 
-What a JSON Schema cannot say is left to `wizards validate`: unique ids, steps and fields that
-refer to each other, templates naming answers that exist by then, and files in the workspace.
+`wizards validate` checks what a JSON Schema cannot say: unique ids, steps and fields that refer
+to each other, templates that name answers that exist by then, and files in the workspace.
 
 ## `wizards validate`
 
@@ -81,8 +92,8 @@ refer to each other, templates naming answers that exist by then, and files in t
 wizards validate invoice.wizard
 ```
 
-It checks a wizard the way the studio's import does, with no running studio and no account.
-It takes any number of paths:
+It checks a wizard the way the studio’s import does, without a running studio and without an
+account. It takes any number of paths:
 
 | Path | Read as |
 |---|---|
@@ -96,12 +107,13 @@ It takes any number of paths:
   "{{nope}}" refers to a field that is not asked before "g".
 ```
 
-`--json` prints the issues as JSON. The exit code is `0` when every wizard is fine, `1` when one
-has issues and `2` when no path was given. That is enough for a check in CI:
+A wizard without issues gets a ✓ with its number of steps and files. `--json` prints the
+results as JSON. The exit code is `0` when every wizard is fine, `1` when one has issues and `2`
+when no path was given. That is enough for a check in CI:
 
 ```bash
 npx wizards validate wizards/*.wizard
 ```
 
-The project's own things are checked on import, because only a project has them: its
-connectors and their actions, its MCP servers and its plugins' tools.
+The import checks what belongs to the space, because only the space has it: its connectors and
+their actions, its connected systems (MCP servers) and its plugins’ tools.

package/apps/runtime/dist/docs/user/ai-apps.md

@@ -1,26 +1,26 @@
 ---
 title: AI apps
 description: Run and build your wizards inside Claude Desktop, Cursor, Codex and other AI apps.
-version: 0.3.2
+version: 0.5.0
 ---
 
-Settings → Integrate brings your wizards to where you work. engenty wizards is an MCP server:
-an AI app that adds it gets the tools to find, run and build wizards. Under "Share" the same page
+Settings → Integrate brings your wizards to where you work. engenty wizards is an MCP server: an
+AI app that adds it gets the tools to find, run and build wizards. Under “Share”, the same page
 has the WordPress plugin: see [WordPress](./wordpress.md).
 
 ## What an app can do
 
 | In the chat | How |
 |---|---|
-| Run a wizard | "Start one of my engenty wizards." The app asks the wizard's questions, shows the review and hands over the downloads. Only published wizards run |
-| See the wizard itself | Apps that show MCP Apps show the wizard as a widget, page by page, and you answer there |
-| Build a wizard | "Use engenty wizards to build a wizard that reads amount, date and sender from an invoice PDF." |
-| Change one | Create, change and publish wizards, find templates and connectors, read and write a wizard's files |
+| Run a wizard | “Start one of my engenty wizards.” The app asks the wizard’s questions, shows the review and hands over the downloads. Only published wizards run |
+| See the wizard itself | Apps that support MCP Apps show the wizard as a widget, page by page, and you answer there |
+| Build a wizard | “Use engenty wizards to build a wizard that reads amount, date and sender from an invoice PDF.” |
+| Change one | The app can create, change and publish wizards, find templates and connectors, and read and write a wizard’s files |
 
 - A run in a chat spends what any run of the wizard spends, and so does a test run.
-- What a chat cannot fill in — files, recordings, signatures, line items — is done on the run's
-  page in the browser. The app hands you the link.
-- What an app writes shows up live in an open editor, marked with the app's name.
+- What a chat can’t fill in (files, recordings, signatures, line items) you fill in on the run’s
+  page in the browser. The app gives you the link.
+- What an app writes shows up live in an open editor, marked with the app’s name (“Via …”).
 
 ## Apps
 
@@ -40,68 +40,71 @@ has the WordPress plugin: see [WordPress](./wordpress.md).
 
 ## Add an app
 
-Settings → Integrate opens on the apps found on this computer, each with one button and where it
-stands: works, added but not tested yet, or not set up. The dots in the menu say the same.
+Settings → Integrate opens on the apps found on this computer. Each one has a button and says
+where it stands: “Works”, “Added, not tested yet” or “Not set up yet”. The dots in the menu say
+the same.
 
-Pick an app and follow its numbered steps:
+Choose an app and follow its numbered steps:
 
-1. **Add to …** writes engenty wizards into the app's settings. No key, no port: the app starts
-   engenty wizards itself.
-2. **Restart the app**, or reload its MCP servers. The page notices by itself when the app checks
-   in.
-3. **Try it in the chat**: "Which wizards do I have in engenty?"
+1. **Add to …** writes engenty wizards into the app’s settings. You need no key and no port: the
+   app starts engenty wizards itself.
+2. **Restart …**, or reload the app’s MCP servers. The page notices by itself when the app
+   checks in.
+3. **Try it in the chat**: “Which wizards do I have in engenty?”
 
-Once the app has called a tool, the page says "Works" and offers first sentences to try, with your
-own wizards' names.
+Once the app has used a tool, the page says “Works” and offers first sentences to try, with your
+own wizards’ names.
 
-From a terminal, the same as step 1:
+From a terminal, this command does the same as step 1:
 
 ```bash
 wizards connect
 ```
 
-That adds every AI app found on the computer. Name apps to add only those, and take one out
-again with `disconnect`:
+It adds every AI app found on this computer. To add only some apps, name them. To take an app
+out again, use `disconnect`:
 
 ```bash
 wizards connect cursor codex
 wizards disconnect cursor
 ```
 
-- The file an app's settings were in before is kept beside it as `<file>.before-engenty`.
-- Quit Claude Desktop before you add it: it writes its settings from memory while it runs.
-- A settings file that is not plain JSON is left alone. The command prints the entry to paste.
+- The app’s settings file as it was before is kept beside it as `<file>.before-engenty`.
+- If Claude Desktop is running, the command asks you to quit it first: it writes its settings
+  from memory while it runs and would overwrite the change.
+- A settings file that isn’t plain JSON is left alone. The command prints the entry for you to
+  paste in yourself.
 
 ## An app on another computer
 
-Under the steps, "Connect with the address and an API key" is for an app that runs elsewhere. The
-API key is shown once and goes straight into the command or config entry the page shows.
+Under the steps, “Connect with the address and an API key” is for an app that runs elsewhere.
+The API key is shown once and goes straight into the command or settings entry the page shows.
 
-- Each API key signs one app in and has every right: treat it like a password.
-- The page lists the API keys with their last use. Delete one and that app is signed out.
+- Each API key signs in one app and has full rights. Treat it like a password.
+- The page lists the API keys with their last use. When you delete one, that app is signed out.
 
 ## Apps on the web
 
-claude.ai and ChatGPT connect from their makers' servers, and so do Claude Desktop's connectors.
-They cannot reach your computer: for them your wizards run on engenty.ai.
+claude.ai and ChatGPT connect from their makers’ servers, and so do Claude Desktop’s
+connectors. They can’t reach your computer, so for them your wizards run on engenty.ai.
 
-- **From the cloud studio** the page walks through it: open the app's connector settings, enter
-  the name and the address `https://engenty.ai/api/mcp`, click Connect, sign in at engenty and
-  allow. No key.
-- **From your computer** connect your engenty account first. The wizards you publish go to
-  engenty.ai, and claude.ai connects there. Without an account, use Claude Desktop on this
-  computer.
+- **In the studio on engenty.ai**, the page walks you through it: open the app’s connector
+  settings, enter the name and the address `https://engenty.ai/api/mcp`, click “Connect”, sign
+  in to engenty and choose “Allow”. You need no key.
+- **On your computer**, connect your engenty account first (“Connect to engenty.ai”). The wizards
+  you publish then go to engenty.ai, and claude.ai connects there. If you’d rather not use an
+  account, use Claude Desktop on this computer.
 
 The consent page names the team the access is for and the address it goes back to. An app that
-only named itself is marked "Name given by the app itself".
+only named itself is marked “Name given by the app itself”.
 
-Disconnect an app under Account → Connected apps at engenty.ai. Its access ends within half a
-minute, even with a token it already holds.
+You disconnect an app at engenty.ai under Account → Connected apps. Its access ends within half
+a minute, even with a token it already holds.
 
 ## The Claude Code plugin
 
-With a public https address, Claude Code can also install a plugin. It adds the `/wizard`
-command and the skills to build and to use wizards:
+If engenty wizards has a public https address, Claude Code can also install a plugin. It adds
+the `/wizard` command and the skills to build and use wizards:
 
 ```bash
 claude plugin marketplace add <your address>/api/claude-plugin/marketplace.json