wizards 0.4.7 → 0.5.1

package/apps/runtime/dist/docs/dev/index.md

@@ -1,39 +1,41 @@
 ---
 title: Developer
-description: Extend engenty wizards with plugins — tools for AI steps, routes with their own tables, pages in the studio.
-version: 0.3.2
+description: Extend engenty wizards with plugins – tools for AI steps, routes with their own tables, pages in the studio.
+version: 0.5.0
 ---
 
-engenty wizards is extended with **plugins**. A plugin adds to a runtime without changing its
-code, and it loads from its files while the app runs.
+You extend engenty wizards with **plugins**. A plugin adds to a runtime without changing its
+code, and the runtime loads it from its files while it runs.
 
 ## Start here
 
 | | |
 |---|---|
-| [What a plugin is](./plugins/index.md) | The two halves, what each can add, what a plugin may touch |
-| [Quick start](./plugins/quick-start.md) | A tool for AI steps in one file, working in two minutes |
+| [What a plugin is](./plugins/index.md) | The two halves, what each can add and what a plugin may touch |
+| [Quick start](./plugins/quick-start.md) | A tool for AI steps in one file that works in two minutes |
 | [Reference](./plugins/reference.md) | Every call, type, address and setting |
 | [Examples](./plugins/examples.md) | Two plugins to read and copy |
 
 ## Wizards as files
 
-A wizard is JSON, and it travels as a `.wizard` package. Its format, the JSON Schema for your
-editor and `wizards validate` are on [The wizard format](./wizard-format.md).
+A wizard is JSON, and it travels as a `.wizard` file. [The wizard format](./wizard-format.md)
+describes the format, the JSON Schema for your editor and `wizards validate`.
 
 ## What you need
 
-- An install of engenty wizards, or a checkout of
+- engenty wizards on your computer, or a checkout of
   [engenty/wizards](https://github.com/engenty/wizards).
-- TypeScript. A plugin's server half is read as TypeScript, without a build.
-- A checkout, if your plugin draws in the studio: its studio half is built with the studio's
+- TypeScript. The runtime reads a plugin’s server half as TypeScript, without a build.
+- A checkout, if your plugin draws in the studio: you build its studio half with the studio’s
   own tools.
 
 ## Working on engenty wizards itself
 
-These pages are about extending it. The code's own documents are in the repository:
+These pages are about extending engenty wizards. The documents about its own code are in the
+repository:
 
 | | |
 |---|---|
-| [docs/development.md](https://github.com/engenty/wizards/blob/main/docs/development.md) | Run it from source, the checks, how it is built, releases |
-| [docs/marketplace-contract.md](https://github.com/engenty/wizards/blob/main/docs/marketplace-contract.md) | What a runtime and the marketplace speak |
+| [docs/development.md](https://github.com/engenty/wizards/blob/main/docs/development.md) | How to run it from source, the checks, how it is built and how it is released |
+| [docs/marketplace-contract.md](https://github.com/engenty/wizards/blob/main/docs/marketplace-contract.md) | What a runtime and the marketplace say to each other |
+| [docs/copy-style.md](https://github.com/engenty/wizards/blob/main/docs/copy-style.md) | How the app talks to people: the voice, the glossary and the rules for every string |

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

@@ -1,13 +1,14 @@
 ---
 title: Accounts
-description: Accounts a plugin connects for a space — a calendar, a mailbox — through the runtime's built-in connectors.
-version: 0.3.2
+description: Accounts a plugin connects for a space, such as a calendar or a mailbox, through the runtime's built-in connectors.
+version: 0.5.0
 ---
 
-A wizard's connections belong to the person who runs it. A plugin that works for the whole
-space, a calendar that every booking wizard reads, connects an account of its own:
-`server.connections`. It uses the runtime's built-in OAuth connectors (Google, Microsoft, Slack,
-GitHub, HubSpot …), keeps the tokens sealed in the tenant's database, and refreshes them.
+A wizard’s connections belong to the person who runs it. A plugin that works for the whole
+space, such as a calendar that every booking wizard reads, connects an account of its own with
+`server.connections`. It uses the runtime’s built-in connectors (Google, Microsoft, Slack,
+GitHub, HubSpot, S3 …). The runtime keeps the tokens and keys sealed in the tenant’s database and
+refreshes the tokens.
 
 ```ts
 const ACTIONS = ["list_events", "create_event", "delete_event"];
@@ -28,44 +29,46 @@ const { events } = await server.connections.call<{ events: unknown[] }>(account.
 
 | `server.connections.` | Does |
 |---|---|
-| `available(ids)` | Of these connector ids, the ones a person can connect here now: `{ id, name, auth }`, and for `auth: "api_key"` the `fields` to ask for (`key`, `label`, `placeholder`, `required`, `secret`). An OAuth connector is offered once its client is set up (`GOOGLE_OAUTH_CLIENT_ID` …), and on a local install Google also through the linked account; a connector that takes keys (HubSpot, S3) always |
-| `start({ space, connector, actions, lang? })` | An OAuth connector: the provider's sign-in page. Only the rights `actions` need are asked for. `lang` (`"en"` or `"de"`) is the language of the page the person comes back to; without it, their browser's |
-| `connect({ space, connector, actions, credentials })` | A connector that takes keys: the keys by field key, tried once at the provider, then kept sealed. Keys the provider refuses throw an error with the status `400` and the code `credentials`, whose message says what was wrong. Answers the connection |
-| `list(space)`, `get(id)` | What is connected: `{ id, space, connector, label, actions, createdAt }`, the newest first. `label` is the account as the provider names it |
-| `call(id, action, input)` | Runs one of the connector's actions with the account. A fresh token is fetched first when the old one runs out |
+| `available(ids)` | Returns the connectors of these ids that a person can connect here now: `{ id, name, auth }`, and for `auth: "api_key"` the `fields` to ask for (`key`, `label`, `placeholder`, `required`, `secret`). An OAuth connector is offered once its client is set up (`GOOGLE_OAUTH_CLIENT_ID` …) or when it registers a client itself. On a local install Google is also offered through the linked engenty account. A connector that takes keys (HubSpot, S3) is always offered |
+| `start({ space, connector, actions, lang? })` | Returns the provider’s sign-in page of an OAuth connector. The provider asks only for the rights that `actions` need. `lang` (`"en"` or `"de"`) is the language of the page the person comes back to; without it, the page follows their browser |
+| `connect({ space, connector, actions, credentials })` | Connects a connector that takes keys. `credentials` holds the keys by field key. The runtime tries them once at the provider and then keeps them sealed. Keys the provider refuses throw an error with the status `400` and the code `credentials`, whose message says what was wrong. Returns the connection |
+| `list(space)`, `get(id)` | Return what is connected: `{ id, space, connector, label, actions, createdAt }`, the newest first. `label` is the account as the provider names it, often an email address |
+| `call(id, action, input)` | Runs one of the connector’s actions with the account. When the token has run out, the runtime fetches a fresh one first |
 | `remove(id)` | Forgets the connection and its tokens |
 
 ## Signing in
 
-`start` gives an address; open it in a window from the studio half. The provider sends the
-person back to the runtime (`/api/connect/callback`, the address a wizard's connections use), the
-runtime keeps the account under the plugin and the space, and the window posts a message to the
-studio and closes:
+`start` returns an address. Open it in a window from the studio half. The provider sends the
+person back to the runtime (`/api/connect/callback`, the address a wizard’s connections use too).
+The runtime keeps the account under the plugin and the space. The window then posts
+`{ type: "wizards:connected", ok }` to the studio and closes:
 
 ```tsx
 const { url } = await studio.api.post<{ url: string }>(`/connect?space=${space.id}`);
 window.open(url, "connect", "width=520,height=700");
 
 window.addEventListener("message", (event) => {
-  if (event.data?.type === "wizards:connected") {
+  if (event.data?.type === "wizards:connected" && event.data.ok) {
     refetch();
   }
 });
 ```
 
-- A second sign-in to the same account for the same space replaces the first one's tokens and
-  actions; it does not add a second connection.
+- A second sign-in to the same account for the same space replaces the first one’s tokens and
+  actions. It does not add a second connection.
 - A local install without a Google client of its own connects Google through the linked
-  engenty account. Without a linked account `start` throws an error with the status `409` and
+  engenty account. Without a linked account, `start` throws an error with the status `409` and
   the code `account`, whose message says what to do.
 
 ## What `call` refuses
 
-- An action the connection was not made for: connect again with that action in `actions`.
-- What the provider refuses: its error, with the status and the first words of its answer. A
-  connection the person removed at the provider answers so on the next call.
+- An action the connection was not made for. Connect again with that action in `actions`.
+- What the provider refuses. `call` throws the provider’s error, with the status and the first
+  words of its answer. If the person removed the connection at the provider, the next call
+  fails this way.
 
 ## Where it is kept
 
-The table `plugin_connection` of the tenant's database, by plugin and space. A plugin sees only
-its own connections. Deleting a space deletes them. Unloading or removing the plugin leaves them.
+The connections are kept in the table `plugin_connection` of the tenant’s database, by plugin
+and space. A plugin sees only its own connections. Deleting a space deletes them. Unloading or
+removing the plugin leaves them in place.

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

@@ -1,7 +1,7 @@
 ---
 title: Events
-description: Do something when a run ends or a space changes — keep who it was, post a message, read a new document.
-version: 0.3.2
+description: Do something when a run ends or a space changes – keep who it was, post a message, read a new document.
+version: 0.5.0
 ---
 
 A plugin can listen to runs that reach their end, and to spaces that change.
@@ -35,12 +35,14 @@ server.on("run.done", async ({ run, wizard, values }) => {
 
 | Event | A space | Gets |
 |---|---|---|
-| `space.created` | was made, here or by a local install's sync | `{ space: { id } }` |
-| `space.updated` | changed its title, about, colours, facts or systems | `{ space: { id } }` |
+| `space.created` | was made here, or arrived from engenty wizards on someone’s computer | `{ space: { id } }` |
+| `space.updated` | changed its name, its brand (Info & brand), its facts or its connected systems, or arrived again from a computer | `{ space: { id } }` |
 | `space.deleted` | was deleted | `{ space: { id } }` |
 | `space.file.ready` | has a file that was read: a document is in the index now | `{ space: { id }, file: { id, name, kind, mime } }` |
 | `space.file.removed` | lost a file | `{ space: { id }, file: { id, name, kind, mime } }` |
 
+`file.kind` is `"document"`, `"logo"`, `"asset"` or `"pattern"`.
+
 ```ts
 // A document arrived: read it into the wiki.
 server.on("space.file.ready", async ({ space, file }) => {
@@ -50,7 +52,7 @@ server.on("space.file.ready", async ({ space, file }) => {
 });
 ```
 
-The space events are not waited for: the request that changed the space answers before its
+Nothing waits for the space events: the request that changed the space answers before its
 listeners are done.
 
 ## What a run listener gets
@@ -58,24 +60,24 @@ listeners are done.
 | | |
 |---|---|
 | `run.id`, `run.wizardId` | The run and its wizard |
-| `run.mode` | `"live"`: a real run, over the wizard's link or from an AI app. `"test"`: a test run |
+| `run.mode` | `"live"`: a real run, over the wizard’s link or from an AI app. `"test"`: a test run |
 | `run.status` | `"done"`, `"failed"` or `"cancelled"` |
 | `wizard` | `{ id, title, projectId }` |
 | `values` | What the person answered, by field id |
 
-`values` holds answers as the wizard asked for them. Which fields exist depends on the wizard: a
-listener that wants an e-mail address looks for a field with the id it expects and does nothing
-when it is missing. Check the type of every value you use.
+`values` holds the answers as the wizard asked for them. Which fields exist depends on the
+wizard. A listener that wants an email address looks for a field with the id it expects and does
+nothing when it is missing. Check the type of every value you use.
 
 ## Rules a listener runs under
 
-- **Inside the run's tenant.** `server.getTenantDb()` is that tenant's database.
-- **After the run ended.** A listener cannot change the run or its result.
-- **It cannot fail the run.** A listener that throws is logged with the plugin's id.
-- **It can be told twice.** A finished run that is redone and ends again fires the event again.
-  Write listeners so that a second call does no harm: update a row instead of adding one, or
-  remember the run's id.
-- **Nobody waits for it.** Give outside calls a time limit:
+- **It runs inside the run’s tenant.** `server.getTenantDb()` is that tenant’s database.
+- **It runs after the run ended.** A listener cannot change the run or its result.
+- **It cannot fail the run.** A listener that throws is logged with the plugin’s id.
+- **It can be called twice.** A finished run that is redone and ends again fires the event
+  again. Write listeners so that a second call does no harm: update a row instead of adding one,
+  or remember the run’s id.
+- **Nothing waits for it.** Give outside calls a time limit:
 
   ```ts
   await fetch(url, { method: "POST", body, signal: AbortSignal.timeout(10_000) });
@@ -84,4 +86,4 @@ when it is missing. Check the type of every value you use.
 ## Test runs
 
 Test runs fire the same events with `run.mode === "test"`. A plugin that keeps data about real
-people, or tells someone outside, leaves them out, as the example above does.
+people, or tells someone outside, leaves test runs out, as the example above does.

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

@@ -1,7 +1,7 @@
 ---
 title: Examples
 description: Two plugins in the repository to read, run and copy.
-version: 0.3.2
+version: 0.5.0
 ---
 
 The repository has two example plugins. Load them from a checkout with one line in `.env.local`:
@@ -13,7 +13,7 @@ PLUGINS_DIR=examples/plugins
 ## notify: one file
 
 [examples/plugins/notify.ts](https://github.com/engenty/wizards/blob/main/examples/plugins/notify.ts)
-posts a line to an address whenever a real run of a wizard reached its end.
+posts a line to an address whenever a real run of a wizard reaches its end.
 
 ```ts
 import type { WizardsPluginFactory } from "@engenty-wizards/plugin-sdk";
@@ -42,8 +42,8 @@ export default plugin;
 
 | It shows | |
 |---|---|
-| A plugin of one file | Its id is the file's name |
-| A setting | `NOTIFY_URL` in the install's `.env`, read at load time |
+| A plugin of one file | Its id is the file’s name |
+| A setting | `NOTIFY_URL` in the install’s `.env`, read at load time |
 | A listener | Test runs left out, a time limit on the call |
 
 ## run-log: both halves
@@ -58,8 +58,8 @@ keeps a line for every run that ended and shows them in the studio.
 | `migrations/0002_space.sql` | A column added later: the space of each line |
 | `src/schema.ts` | The same table for Drizzle |
 | `src/plugin.ts` | A listener on the three run events (`run.done`, `run.failed`, `run.cancelled`), two routes (one for admins only, one that filters by space) and a tool, `run-log.recent` |
-| `ui/messages.ts` | Words in German and English |
-| `ui/plugin.tsx` | A section of the space page with the space's last runs, under Results, a page with the whole log, and a section of the settings that empties the log |
+| `ui/messages.ts` | Its texts in English and German |
+| `ui/plugin.tsx` | A section of the space page under Results with the space’s last runs, a page with the whole log, and a settings section that empties the log |
 | `package.json` | A workspace package whose `build` script builds the studio half |
 
 Build its studio half once, or on every save:
@@ -75,11 +75,12 @@ node scripts/build-plugin.mjs examples/plugins/run-log --watch
 Then, in the studio:
 
 1. Test a wizard to its end.
-2. The house icon in the app bar opens the space's page; under Results, "Runs" stands below the
-   results: the last five runs of the space's wizards. Its last line opens the page with the
-   whole log.
-3. Settings → Runs shows how many lines are kept and deletes them.
-4. An AI step can list the tool "Run log" and tell how the last runs ended.
+2. Open the space’s Results: choose “Results” under Space in the sidebar, or open the space’s
+   page with the house icon in the app bar and go to Results. “Runs” stands below the results
+   and shows the last five runs of the space’s wizards. Its last line, “All … runs”, opens the
+   page with the whole log.
+3. Settings → Runs shows how many lines are kept, and “Delete all” deletes them.
+4. An AI step can list the tool “Run log” and tell how the last runs ended.
 
 ## The plugin of these pages
 
@@ -97,4 +98,4 @@ The `contacts` plugin these pages build up, piece by piece:
 
 [apps/runtime/test/plugins.test.ts](https://github.com/engenty/wizards/blob/main/apps/runtime/test/plugins.test.ts)
 writes small plugins into a folder and exercises them: finding, loading, a plugin that fails,
-routes, tables per tenant, tools in a run, events, reloading.
+routes, tables per tenant, tools in a run, events and reloading.

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

@@ -1,31 +1,34 @@
 ---
 title: Plugins
 description: What a plugin is, what its two halves can add, and what it may touch.
-version: 0.3.2
+version: 0.5.0
 ---
 
-A plugin adds to a runtime without changing its code. The runtime finds plugins at start, loads
-them from their files and loads one again when its files change.
+A plugin adds to a runtime without changing its code. The runtime finds plugins when it starts,
+loads them from their files and loads a plugin again when its files change.
 
 ## What a plugin can add
 
 | It adds | Where it shows | Page |
 |---|---|---|
-| A tool for AI steps | In a step's tool list, in the assistant's and the MCP authoring guide | [Tools](./tools.md) |
-| A runner: a door a wizard runs through, with the run API that drives runs from it | In the share dialog's channels, at `/w/<token>/<runner>`, on the wizard's first page | [Runners](./runners.md) |
-| A block and tools for every AI step of a space | In the steps' instructions | [The space](./space.md) |
-| Pages, tables and files of a space's Knowledge, with Kategorien | In Knowledge, and in what `project_search` finds | [The space](./space.md#knowledge-a-plugin-writes) |
-| Texts in a space's search index | In what `project_search` finds | [The space](./space.md#the-search-index) |
-| Tools of the studio's assistant, and their cards | In the assistant's chat, on every page | [The space](./space.md#tools-of-the-space-assistant) |
-| Routes | Below `/api/studio/plugins/<id>`, for programs with a key below `/api/v1/plugins/<id>`; public ones below `/api/public/plugins/<id>` | [Routes](./routes.md) |
-| Tables | In every tenant's database | [Tables](./tables.md) |
+| A tool for AI steps | In a step’s tool list, in the assistant’s and the MCP authoring guide | [Tools](./tools.md) |
+| A runner: a door a wizard runs through, with the run API that drives runs from it | In the share dialog’s channels, at `/w/<token>/<runner>`, on the wizard’s first page | [Runners](./runners.md) |
+| A runner’s settings and setup in the share dialog | In the share dialog, behind its gear and behind “Set up” in the runner’s row | [Runners](./runners.md#the-runners-part-of-the-share-dialog) |
+| A block and tools for every AI step of a space | In the steps’ instructions | [The space](./space.md) |
+| Pages, tables and files of a space’s Knowledge, with their categories | In Knowledge, and in what `project_search` finds | [The space](./space.md#knowledge-a-plugin-writes) |
+| Texts in a space’s search index | In what `project_search` finds | [The space](./space.md#the-search-index) |
+| Tools of the studio’s assistant, and their cards | In the assistant’s chat, on every page. For now the assistant is off unless it is switched on | [The space](./space.md#tools-of-the-space-assistant) |
+| Routes | Below `/api/studio/plugins/<id>`, for programs with a key below `/api/v1/plugins/<id>`; public ones below `/api/public/plugins/<id>`, one for every tenant below `/api/public/plugins/<id>/shared` | [Routes](./routes.md) |
+| Tables | In every tenant’s database | [Tables](./tables.md) |
 | A listener on runs that end and spaces that change | Nowhere: it works in the background | [Events](./events.md) |
 | A job, again and again | Nowhere: it works in the background | [The server half](./server.md#jobs) |
-| An account of a space (a calendar, a mailbox), signed in through a built-in connector | Where the plugin's own pages offer it | [Accounts](./connections.md) |
+| The team’s own number for texts and calls, on engenty.ai | Where the plugin’s runner and pages use it | [The server half](./server.md#numbers-of-the-manage-app) |
+| An account of a space (a calendar, a mailbox), signed in through a built-in connector | Where the plugin’s own pages offer it | [Accounts](./connections.md) |
 | A wizard as a template | First among the templates of a new wizard, and in the MCP `list_starters` | [Starters](./starters.md) |
 | A page of the studio | Behind an icon in the app bar, or at its address | [The studio half](./studio.md) |
-| A section of the settings | In the settings' list | [The studio half](./studio.md) |
-| A section of the space page | In one of its parts, below the part's own sections | [The studio half](./studio.md#the-space) |
+| A section of the settings | In the settings’ list | [The studio half](./studio.md) |
+| A section of the space page | In one of its parts, below the part’s own sections | [The studio half](./studio.md#the-space) |
+| A part of the space page | In the space’s menu, beside Info & brand, Knowledge, Data and Results | [The studio half](./studio.md#a-part-of-the-plugins-own) |
 
 ## Two halves
 
@@ -35,9 +38,9 @@ them from their files and loads one again when its files change.
 | Runs in | The runtime | The studio, after sign-in |
 | Loaded | As TypeScript, no build | As the built script |
 | Types | `@engenty-wizards/plugin-sdk` | `@engenty-wizards/plugin-sdk/studio` |
-| Adds | Tools, runners, routes, tables, listeners, jobs, starters, accounts, Knowledge, the space's block, index and assistant tools | Pages, icons in the app bar, sections of the settings and of the space page, a runner's part of the share dialog, cards in the assistant's chat |
+| Adds | Tools, runners, routes, tables, listeners, jobs, starters, accounts, Knowledge, the space’s block, index and assistant tools | Pages, icons in the app bar, sections of the settings and of the space page, parts of the space page, a runner’s settings and setup in the share dialog, cards in the assistant’s chat |
 
-A plugin has one half or both. The studio half talks to the server half over the plugin's own
+A plugin has one half or both. The studio half talks to the server half over the plugin’s own
 routes.
 
 ```mermaid
@@ -53,21 +56,23 @@ flowchart LR
 
 ## What a plugin may touch
 
-A plugin runs inside the runtime's process with all of its rights. It reads every tenant's data,
-the install's settings and the files of the machine. There is no sandbox and no permission list.
+A plugin runs inside the runtime’s process with all of its rights. It can read every tenant’s
+data, the install’s settings and the files of the computer it runs on. There is no sandbox and
+no permission list.
 
 - Install only code you know.
 - A plugin for others says in its own description what it reads and where it sends it.
 
 ## Not the Claude Code plugin
 
-The "Claude Code plugin" of engenty wizards is something else: what a runtime hands to Claude
-Code (`plugin/` in the repository). These pages are about plugins of the runtime.
+The “Claude Code plugin” of engenty wizards is something else: it is what a runtime hands to
+Claude Code (`plugin/` in the repository). These pages are about plugins of the runtime.
 
 ## Not there yet
 
-- Connectors of its own, tools for MCP clients and AI clients from a plugin. A plugin connects
+- A plugin can’t bring connectors of its own, or tools for MCP clients and AI apps. It connects
   accounts through the built-in connectors: [Accounts](./connections.md).
-- New kinds of steps or fields: the public pages of a wizard load no plugin. A plugin's runner
-  is served whole at its own sub-path; nothing is loaded into the page or the chat.
-- Building a studio half without a checkout of the repository.
+- A plugin can’t add new kinds of steps or fields: the public pages of a wizard load no plugin.
+  A plugin’s runner is served whole at its own sub-path; nothing is loaded into the page or the
+  chat.
+- You can’t build a studio half without a checkout of the repository.

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

@@ -1,7 +1,7 @@
 ---
 title: Files and manifest
 description: Where the runtime looks for plugins, what counts as one, and what engenty.plugin.json says.
-version: 0.3.2
+version: 0.5.0
 ---
 
 ## Where the runtime looks
@@ -12,9 +12,9 @@ version: 0.3.2
 | Each folder of `PLUGINS_DIR` (comma-separated) | Plugins of this install |
 
 - An installed app looks in `~/.engenty/wizards/plugins` unless its `.env` names another folder.
-- From a checkout `PLUGINS_DIR` is empty. `PLUGINS_DIR=examples/plugins` in `.env.local` loads
+- In a checkout `PLUGINS_DIR` is empty. `PLUGINS_DIR=examples/plugins` in `.env.local` loads
   the examples.
-- A runtime that watches its plugins makes a folder of `PLUGINS_DIR` that is missing.
+- A runtime that watches its plugins creates a folder of `PLUGINS_DIR` that is missing.
 
 ## What counts as a plugin
 
@@ -22,17 +22,18 @@ In such a folder:
 
 | Entry | Is |
 |---|---|
-| `notify.ts`, `notify.js` | A plugin of one file. Its id is the file's name |
+| `notify.ts`, `notify.js` | A plugin of one file. Its id is the file’s name |
 | `contacts/engenty.plugin.json` | A plugin with a manifest |
-| `hello/index.ts`, `hello/index.js` | A plugin without a manifest. Its id is the folder's name |
+| `hello/index.ts`, `hello/index.js` | A plugin without a manifest. Its id is the folder’s name |
 | `node_modules/<package>`, `node_modules/@scope/<package>` | Installed packages that carry a manifest |
 
-- Names that begin with `.` or `_` are skipped.
-- `.mjs` files are not read: Node keeps such a file once imported, so it could not load again.
-- Of two plugins with one id the first found stays. The other shows under "Not a plugin" in
-  Settings → Plugins, as does a manifest that cannot be read.
+- The runtime skips names that begin with `.` or `_`.
+- It doesn’t read `.mjs` files: Node keeps such a file once it is imported, so it could not load
+  again.
+- Of two plugins with the same id, the first one found stays. The other shows under “Not a
+  plugin” in Settings → Plugins, as does a manifest that cannot be read.
 
-## A plugin's folder
+## A plugin’s folder
 
 ```
 contacts/
@@ -50,39 +51,39 @@ contacts/
   package.json            only if it has dependencies of its own
 ```
 
-Only the manifest is required. A plugin with a studio half is a folder with a manifest.
+Only the manifest is required. A plugin with a studio half must be a folder with a manifest.
 
 ## The manifest
 
-`engenty.plugin.json` is the file an engenty module has. Fields this runtime does not know are
-kept as they are.
+`engenty.plugin.json` is the same file an engenty module has. The runtime keeps fields it
+doesn’t know as they are.
 
 ```json
 {
   "id": "contacts",
   "name": "Contacts",
   "version": "0.1.0",
-  "description": "Keeps the e-mail address of everyone who ran a wizard to its end."
+  "description": "Keeps the email address of everyone who ran a wizard to its end."
 }
 ```
 
 | Field | | Default |
 |---|---|---|
-| `id` | Lower case, digits and `-`, starting with a letter, at most 40 characters. Part of the plugin's addresses and of its tools' ids | required |
+| `id` | Lower case, digits and `-`, starting with a letter, at most 40 characters. Part of the plugin’s addresses and of its tools’ ids | required |
 | `name` | Shown in the settings | required |
 | `version` | Shown in the settings | `0.0.0` |
 | `description` | Shown in the settings | |
-| `server` | The server half, from the plugin's folder | `src/plugin.ts`, then `src/plugin.js`, then `dist/plugin.js` |
+| `server` | The server half, from the plugin’s folder | `src/plugin.ts`, then `src/plugin.js`, then `dist/plugin.js` |
 | `studio` | The built studio half | `dist/client.js` |
-| `styles` | The built studio half's styles | `dist/client.css` |
+| `styles` | The built studio half’s styles | `dist/client.css` |
 
-A path in the manifest must stay inside the plugin's folder.
+A path in the manifest must stay inside the plugin’s folder.
 
 ## Dependencies
 
 | The plugin imports | It comes from |
 |---|---|
-| `@engenty-wizards/plugin-sdk`, `@engenty-wizards/plugin-sdk/thread`, `zod`, `drizzle-orm`, `drizzle-orm/sqlite-core` | The runtime's own copies, wherever the plugin's file is |
+| `@engenty-wizards/plugin-sdk`, `@engenty-wizards/plugin-sdk/thread`, `zod`, `drizzle-orm`, `drizzle-orm/sqlite-core` | The runtime’s own copies, wherever the plugin’s file is |
 | Its own files | Beside it, as TypeScript |
 | Anything else | A `node_modules` the plugin brings beside it |
 

package/apps/runtime/dist/docs/dev/plugins/quick-start.md

@@ -1,7 +1,7 @@
 ---
 title: Quick start
 description: A tool for AI steps in one file. No build, no restart.
-version: 0.3.2
+version: 0.5.0
 ---
 
 You write one file. The running app finds it, and every AI step can use the tool in it.
@@ -10,10 +10,10 @@ You write one file. The running app finds it, and every AI step can use the tool
 
 | You run | The folder |
 |---|---|
-| The installed app (`wizards`) | `~/.engenty/wizards/plugins` |
-| A checkout (`pnpm dev`) | The folders `PLUGINS_DIR` names in `.env.local`, for example `PLUGINS_DIR=../my-plugins`. A relative path starts at the checkout's root |
+| engenty wizards on your computer (`wizards`) | `~/.engenty/wizards/plugins` |
+| A checkout (`pnpm dev`) | The folders that `PLUGINS_DIR` names in `.env.local`, for example `PLUGINS_DIR=../my-plugins`. A relative path starts at the checkout’s root |
 
-Start the app. It makes the folder if it is missing and watches it while it runs.
+Start the app. It creates the folder if it is missing and watches it while it runs.
 
 ## 2. Write the plugin
 
@@ -48,21 +48,22 @@ export default definePlugin((wizards) => {
 });
 ```
 
-- The file's name is the plugin's id: `workdays`.
-- The tool's full id is `workdays.count`.
-- `@engenty-wizards/plugin-sdk` and `zod` come from the app. Nothing to install.
+- The file’s name is the plugin’s id: `workdays`.
+- The tool’s full id is `workdays.count`.
+- `@engenty-wizards/plugin-sdk` and `zod` come from the app, so you don’t install anything.
 
 ## 3. See it
 
 The app loaded the file the moment you saved it.
 
-- **Settings → Plugins** lists `workdays`, with `workdays.count` under "Tools for steps".
+- **Settings → Plugins** lists `workdays`, with `workdays.count` under “Tools for steps”.
 - **In the editor**, open an AI step: `workdays.count` is in its list of tools, beside
-  `web_search` and the other built-in ones; the line below the list names it "Working days".
-- **In the conversation**, ask for it: "Add a step that counts the working days between the two
-  dates." The assistant knows the tool from its description.
+  `web_search` and the other built-in ones. The line below the list says “workdays.count =
+  Working days”.
+- **In the editor’s chat**, ask for it: “Add a step that counts the working days between the
+  two dates.” The assistant knows the tool from its description.
 
-In a wizard's definition the step lists the tool by its full id:
+In a wizard’s definition the step lists the tool by its full id:
 
 ```json
 {
@@ -78,10 +79,10 @@ In a wizard's definition the step lists the tool by its full id:
 
 ## 4. Change it
 
-Edit the file and save. The plugin loads again; the next step that runs uses the new code.
+Edit the file and save. The plugin loads again, and the next step that runs uses the new code.
 
-If the file has an error, Settings → Plugins says "The server half did not load" with the
-reason. Mend the file and save again.
+If the file has an error, Settings → Plugins says “The server part didn’t load. Check the plugin
+and reload” with the reason. Fix the file and save it again.
 
 ## Next