@engenty/wizards-runtime 0.7.11 → 0.8.0

package/apps/runtime/dist/db/migrations/tenant/meta/_journal.json

@@ -127,6 +127,13 @@
       "when": 1792271496354,
       "tag": "0017_run_client",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "6",
+      "when": 1792274808825,
+      "tag": "0018_share_job",
+      "breakpoints": true
     }
   ]
 }

package/apps/runtime/dist/db/schema.js

@@ -189,6 +189,25 @@ export const deviceCall = sqliteTable("device_call", {
     answer: text("answer", { mode: "json" }).$type(),
     createdAt: createdAt(),
 }, (t) => [uniqueIndex("device_call_req").on(t.reqId), index("device_call_run").on(t.runId)]);
+/** One result sent or published to a share target: what was asked, what happened, where it is. */
+export const shareJob = sqliteTable("share_job", {
+    id: text("id").primaryKey(),
+    runId: text("run_id")
+        .notNull()
+        .references(() => run.id, { onDelete: "cascade" }),
+    tenantId: text("tenant_id").notNull(),
+    /** The share target's id, and its name and icon when it was sent. */
+    target: text("target").notNull(),
+    name: text("name").notNull(),
+    icon: text("icon").$type().notNull(),
+    status: text("status", { enum: ["running", "done", "failed", "cancelled"] }).notNull(),
+    request: text("request", { mode: "json" }).$type().notNull(),
+    events: text("events", { mode: "json" }).$type().notNull().default([]),
+    result: text("result", { mode: "json" }).$type(),
+    error: text("error"),
+    createdAt: createdAt(),
+    updatedAt: updatedAt(),
+}, (t) => [index("share_job_run").on(t.runId, t.createdAt)]);
 /** What each step of a run cost, in credit micros: the measurements estimates are made from. */
 export const runCost = sqliteTable("run_cost", {
     runId: text("run_id")

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

@@ -1,33 +1,45 @@
 ---
 title: Developer
-description: Extend engenty wizards with plugins – tools for AI steps, routes with their own tables, pages in the studio.
-version: 0.7.3
+description: The wizard format, wizards in other systems and the runner, and plugins that extend engenty wizards.
+version: 0.7.10
 ---
 
-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.
+These pages are for people who write wizards as files, bring them into other systems or extend
+engenty wizards. A wizard is one JSON document. The runner shows it to people page by page, on
+its own page, on a website, in a chat or in your own app.
 
 ## Start here
 
 | | |
 |---|---|
-| [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 |
+| [The wizard format](./wizard-format/index.md) | A wizard as JSON: its steps, fields, templates and branches |
+| [JSON Schema](./wizard-format/validate.md) | The JSON Schema for your editor and `wizards validate` |
+| [Integration](./integration/index.md) | A published wizard for people, for AI apps and for your own code |
+| [Your own UI](./integration/own-ui.md) | Your app draws the run with `@engenty-wizards/runner` |
+| [Plugins](./plugins/index.md) | Tools for AI steps, routes with their own tables, pages in the studio |
 | [The API](./api.md) | What a program may rely on, what is private, and how a client names itself |
 
 ## Wizards as files
 
-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`.
+A wizard is JSON, and it travels as a `.wizard` file. [The wizard format](./wizard-format/index.md)
+describes every step type and field, the `.wizard` file, the JSON Schema for your editor and
+`wizards validate`.
 
 ## Wizards in other systems
 
 [Integration](./integration/index.md) shows how a published wizard reaches other systems: people
-over a link, a website or a channel, AI apps over MCP, and your own code.
+over a link, a website or a channel, AI apps over MCP, and your own code with the runner.
+
+## Plugins
+
+A plugin adds to a runtime without changing its code, and the runtime loads it from its files
+while it runs. Start with [What a plugin is](./plugins/index.md) or the
+[Quick start](./plugins/quick-start.md): a tool for AI steps in one file that works in two
+minutes. The [Reference](./plugins/reference.md) lists every call, type, address and setting,
+and [Examples](./plugins/examples.md) has two plugins to read and copy.
+
+## What you need for a plugin
 
-## What you need
 
 - engenty wizards on your computer, or a checkout of
   [engenty/wizards](https://github.com/engenty/wizards).
@@ -37,7 +49,7 @@ over a link, a website or a channel, AI apps over MCP, and your own code.
 
 ## Working on engenty wizards itself
 
-These pages are about extending engenty wizards. The documents about its own code are in the
+These pages are about wizards and plugins. The documents about its own code are in the
 repository:
 
 | | |

package/apps/runtime/dist/docs/dev/meta.json

@@ -1,7 +1,13 @@
 {
   "title": "Developer",
-  "description": "Extend engenty wizards with plugins: tools for AI steps, routes with their own tables, pages in the studio.",
+  "description": "The wizard format, wizards in other systems and the runner, and plugins that extend engenty wizards.",
   "root": true,
   "icon": "SquareTerminal",
-  "pages": ["index", "wizard-format", "plugins", "integration", "api"]
+  "pages": [
+    "index",
+    "wizard-format",
+    "integration",
+    "plugins",
+    "api"
+  ]
 }

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

@@ -0,0 +1,112 @@
+---
+title: Agent steps
+description: An AI step's instructions, tools, output, model class, decisions, and one run per entry.
+version: 0.7.10
+---
+
+An `agent` step is an AI step. It reads its `instructions`, may call tools, and returns its
+output.
+
+```json
+{
+  "id": "research", "type": "agent", "title": "Look it up",
+  "working": "Searching the web…",
+  "instructions": "Find three current facts about {{topic}}, each with its source.",
+  "tools": ["web_search", "web_fetch"],
+  "output": { "format": "markdown" },
+  "model": "high"
+}
+```
+
+`working` is the line the person sees while the step runs. `instructions` is a template. See
+[Templates](./templates.md).
+
+## Tools
+
+| Key | What the step may use |
+|---|---|
+| `tools` | Built-in tools: `web_search`, `web_fetch`, `browser`, `sandbox`, `image`, `http`, `pages`, `code`. A plugin’s tool by its full id, `<plugin>.<tool>` |
+| `mcp` | Ids of the space’s connected systems (MCP servers) |
+| `connections` | Ids of the wizard’s connections. See [Lists and connections](./lists-and-connections.md) |
+
+A wizard that names a plugin’s tool runs only where that plugin is installed. See
+[Tools](../plugins/tools.md).
+
+Every agent step also has a few tools without listing them: it reads and writes the wizard’s
+lists, reads uploads and documents, and searches the space’s Knowledge.
+
+## Output
+
+`output.format` is `text`, `markdown` (the default) or `json`. A `json` step says what it returns
+with `fields`, one level of keys:
+
+```json
+"output": {
+  "format": "json",
+  "fields": [
+    { "id": "summary", "kind": "text", "description": "Two sentences" },
+    { "id": "offers", "kind": "table", "columns": ["name", "price", "url"] },
+    { "id": "urgent", "kind": "yesno", "description": "Is the request urgent?" }
+  ]
+}
+```
+
+| Kind | What it holds |
+|---|---|
+| `text`, `number` | A text, a number |
+| `list` | A list of texts |
+| `table` | Rows. `columns` fixes the keys every row has |
+| `yesno` | `true` or `false`: the answer to the question in `description` |
+| `choice` | One of `options` |
+| `score` | One level of `options`, lowest first, at most ten |
+
+For nested data, such as days that hold meals, use `schema` instead of `fields`. A step has one of
+the two. `surface` gives the result a view of its own. Both are described on
+[Views and widgets](./views-and-widgets.md#a-view-of-an-agent-steps-result).
+
+Later steps read a `json` step’s keys as `steps.<id>.<key>`.
+
+## Model class and effort
+
+A step names the kind of model it needs, never a model. Which model serves a class is set
+outside the wizard.
+
+| `model` | For |
+|---|---|
+| `classifier` | Routing, yes or no, picking from options, a few values from a text |
+| `standard` | Short copy, calling an API, reformatting |
+| `high` | Research with tools, long documents, reasoning over many sources. The default |
+| `highest` | Hard reasoning or writing code. Several times the cost of `high` |
+
+`effort` (`low`, `medium`, `high`) tells the model how hard to think, where the bound model can be
+told. Leave it out unless a step is clearly simple or clearly hard.
+
+## Decisions
+
+A `classifier` step with no tools whose `json` output holds only `yesno`, `choice` and `score`
+fields is a decision. It is answered in one fast, cheap call. A branch reads its answer, and
+`steps.<id>.<field>.p` is how sure it is, from 0 to 1. See [Branches and loops](./branches.md).
+
+## A plugin tool without a model
+
+`call` runs one tool of a plugin once, with these inputs and no model. Its answer is the step’s
+`json` output, as it is. `instructions` stay empty.
+
+```json
+{
+  "id": "free", "type": "agent", "title": "Free times",
+  "call": { "tool": "appointments.availability", "input": { "duration_minutes": 30, "days": 14 } },
+  "output": { "format": "json", "fields": [{ "id": "slots", "kind": "table", "columns": ["start", "end", "label"] }] }
+}
+```
+
+Use it for data a later page shows unchanged. String inputs are templates.
+
+## One run per entry
+
+`each` runs the step once per entry, at most twenty times. It names a table or list output
+(`steps.<id>.<key>`) or a stored list (`lists.<id>`). The instructions read the entry as
+`{{item.<column>}}`, and `{{index}}` and `{{count}}` say where the run is.
+
+The output is one table, `steps.<id>.rows`: the entry’s columns plus the step’s output fields,
+one row per entry.

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

@@ -0,0 +1,63 @@
+---
+title: Branches and loops
+description: A step's next rules, the conditions they test, decisions in words, and loops back.
+version: 0.7.10
+---
+
+Steps run from top to bottom. A step’s `next` sends the run elsewhere:
+
+```json
+"next": [
+  { "when": { "field": "steps.check.refund", "op": "equals", "value": true }, "goto": "refund" },
+  { "ask": "The person wants an exchange", "goto": "exchange" },
+  { "goto": "done" }
+]
+```
+
+| Rule | Holds when |
+|---|---|
+| `{ when, goto }` | The condition holds |
+| `{ ask, goto }` | A decision finds the statement true of the run |
+| `{ goto }` | No other rule holds: the step’s “otherwise”, one per step |
+
+`goto` is a step id or `end`. The first `when` rule that holds wins. After that, all `ask` rules of
+the step are decided together in one cheap call. When none holds, the otherwise rule sends the
+run on, and without one the next step in the list follows.
+
+A rule has `when` or `ask`, not both. Use `ask` where a rule on one field cannot say it.
+
+## Conditions
+
+```json
+{ "field": "budget", "op": "gt", "value": 1000 }
+```
+
+`field` is a page field’s id, an output of an agent step as `steps.<id>.<field>`, or how many rows
+a stored list has as `lists.<id>.count`. A list of conditions holds when every one holds.
+
+| `op` | Holds when the value |
+|---|---|
+| `equals`, `notEquals` | Is, or is not, `value` |
+| `in` | Is one of a list of values |
+| `empty`, `notEmpty` | Is empty, or is not |
+| `gt`, `lt` | Is greater or less than a number |
+| `contains` | Holds `value`: a multiselect, a list output or a text |
+
+A decision’s answer has a probability: `steps.<id>.<field>.p`, from 0 to 1. A rule can test it,
+for example `{ "field": "steps.check.urgent.p", "op": "gt", "value": 0.8 }`.
+
+The same conditions show or hide fields on a page. See
+[Pages and fields](./pages-and-fields.md#fields-that-show-only-when-they-fit).
+
+## A step only some runs take
+
+Put it right after the step that branches to it. That step’s otherwise rule leads every other run
+past it, and the step itself goes on as the next in the list.
+
+## Loops
+
+A rule that goes back to an earlier step is a loop, for example “improve it until the check
+passes”. The step that runs again sees what it made last time.
+
+`max` says how often a rule may send the run on in one run, up to 50. Afterwards it is skipped.
+Without `max`, a loop is taken at most ten times.

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

@@ -0,0 +1,47 @@
+---
+title: Films
+description: A film step has the AI client on your computer write a film as code, and the runtime renders it.
+version: 0.7.10
+---
+
+A `film` step makes a motion-graphics film. The AI client on your computer (Claude Code) writes
+the film as HTML, CSS and JavaScript in a folder of its own. It looks at its frames and fixes
+them, and engenty wizards renders the MP4.
+
+A film step runs only where Claude Code is set up as your AI subscription. It never runs on
+credits or in the cloud, and it takes 5 to 40 minutes.
+
+```json
+{
+  "id": "film", "type": "film", "title": "Make the film",
+  "brief": "A 30-second explainer of {{product}}, calm and bright. Use the voice-over.",
+  "kit": "kits/explainer.zip",
+  "inputs": { "voice": "steps.voice", "script": "steps.script" },
+  "format": "16:9", "seconds": 30
+}
+```
+
+| Key | What it does |
+|---|---|
+| `brief` | What the film is: story, look, what to use. A template |
+| `skills` | Skill packages the client reads. The default is `["hyperframes"]`. A workspace package is `skills/<name>`, a folder with a `SKILL.md` |
+| `kit` | A style kit in the workspace, as a `.zip`: a showreel made once with its rules, helpers and stills. Every film of the wizard is made to it |
+| `inputs` | What the film is made from: a name (lowercase letters, digits, `-`) → a field id or `steps.<id>` |
+| `format` | `16:9` (the default), `9:16` or `1:1` |
+| `from` | `steps.<id>` of an earlier film step. This film starts from that one’s code and lays it out for its own format |
+| `seconds` | About how long the film runs, 3 to 600 |
+| `model`, `effort` | The model class, `standard` by default. The kit carries the craft |
+
+Files among the inputs (uploads, voice lines, pictures) are copied into `input/<name>/`. Text is
+written to `input/<name>.md`, JSON to `input/<name>.json`.
+
+## A film in steps
+
+A film that convinces is made in stages, each with its own review:
+
+1. An agent step writes the research and the script.
+2. A `generate` step with `asset` `voice` reads the whole script.
+3. The film step makes the film from the voice, the pictures and the script.
+
+The film step finds the word timings in the voice-over itself. Sounds come from a fixed catalog.
+A film leaves the page as a video file, so it shows the EU’s “AI” label in the picture.

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

@@ -0,0 +1,57 @@
+---
+title: Images, video and documents
+description: A generate step makes an image, a video, a voice-over, a document or a dashboard.
+version: 0.7.10
+---
+
+A `generate` step makes one thing, named by `asset`. Its `prompt` is a template. See
+[Templates](./templates.md).
+
+```json
+{
+  "id": "visual", "type": "generate", "title": "Draw the image", "asset": "image",
+  "working": "Drawing the image…",
+  "prompt": "A striking image for this post: {{steps.post}}. No text in the image.",
+  "options": { "aspectRatio": "16:9", "style": "modern editorial, high contrast" }
+}
+```
+
+| `asset` | What `prompt` is | `options` |
+|---|---|---|
+| `image` | What the picture shows | `aspectRatio`, `style` |
+| `video` | What the clip shows | `aspectRatio`, `duration` (4 to 10 seconds), `resolution` (`720p`, the default, or `480p`), `style` |
+| `voice` | The exact text that is read aloud | `style`: how to speak, for example “calm, warm” |
+| `document` | The brief | `template`: `invoice`, `offer`, `briefing`, `letter`, `report` or `free` |
+| `dashboard` | The brief | |
+
+`aspectRatio` is `1:1`, `16:9`, `9:16`, `4:5`, `3:2` or `2:3`. A `document` or `dashboard` step
+takes `model` and `effort` like an [agent step](./agent-steps.md#model-class-and-effort). Images
+and video use the image and video class.
+
+## Starting from a picture
+
+`referenceImage` is the image an image or video starts from. It names an earlier `image` field,
+or an earlier step that made images.
+
+## One result per entry
+
+`each` makes one image or video per entry, at most eight. It names an `image` field with several
+uploads, an earlier step that made several images, or a table of an agent step
+(`steps.<id>.<key>`). The prompt reads the entry as `{{item.<column>}}`, `{{index}}` and
+`{{count}}`. With `each` the prompt goes to the model as written, so let the agent step that makes
+the table write complete descriptions.
+
+With `referenceImage` naming as many images, entry 3 starts from the third image. In a review the
+person can make single results again.
+
+## Photos and signatures in documents
+
+A document step can place the photos of an earlier `image` field and a `signature`. Say in its
+prompt where they go. Pictures from the web in a document (`<img src="https://…">`) are fetched
+once when the step runs and kept with the run.
+
+## AI labels
+
+Images, clips and voice-overs carry the marking of AI media (EU AI Act, Art. 50) in their file
+metadata. The runner lays the EU’s “AI” label over them. Never ask an image step to draw a label
+into the picture.

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

@@ -0,0 +1,188 @@
+---
+title: The wizard format
+description: A wizard as one JSON document, what its keys mean, and where each part is described.
+version: 0.7.10
+---
+
+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 its [JSON Schema](#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
+tool may read and write wizards.
+
+## The definition
+
+```json
+{
+  "$schema": "https://engenty.ai/schema/v1/wizard.json",
+  "version": 1,
+  "title": "Create an invoice",
+  "description": "A finished invoice from a few details.",
+  "avatar": "round",
+  "lang": "en",
+  "steps": [ … ]
+}
+```
+
+| Key | What it holds |
+|---|---|
+| `version` | The version of the format, `1`. See [Version](#version) |
+| `title` | What people get, short. See [Title, description and intro](#title-description-and-intro) |
+| `description` | One sentence about the wizard |
+| `avatar` | The engenty shown to people. See [The avatar](#the-avatar) |
+| `intro` | One sentence in the wizard’s voice, in the chat |
+| `lang` | The language the wizard speaks, as a two-letter code. See [Languages](#languages) |
+| `lists` | Tables the wizard keeps between runs. See [Lists and connections](./lists-and-connections.md) |
+| `connections` | Accounts the person connects during a run. See [Lists and connections](./lists-and-connections.md) |
+| `steps` | What the run does, from top to bottom |
+
+## JSON Schema
+
+| For | Schema |
+|---|---|
+| A definition | [`https://engenty.ai/schema/v1/wizard.json`](https://engenty.ai/schema/v1/wizard.json) |
+| `wizard.json` in a `.wizard` file | [`https://engenty.ai/schema/v1/wizard-package.json`](https://engenty.ai/schema/v1/wizard-package.json) |
+
+Put the address under `"$schema"`, as in the example above. Editors such as VS Code then
+complete keys and mark mistakes as you type. [JSON Schema and validation](./validate.md) says
+what the schema checks and what only `wizards validate` can.
+
+## Title, description and intro
+
+| Key | Where people read it | How to write it |
+|---|---|---|
+| `title` | On the wizard’s page, in its chat, in the link preview, in the studio and the marketplace, and in AI apps over MCP | What people get, in a few words: “Create an invoice” |
+| `description` | Under the title, as the chat’s first line and in the link preview. AI apps read it to pick the wizard | One sentence on what comes out |
+| `intro` | In the chat, after the description | One sentence in the wizard’s own voice: “Show me your fridge.” |
+
+`title` is required. `description` may be empty and `intro` left out. All three are written in
+the wizard’s language and translated with it. See [Languages](#languages).
+
+## The avatar
+
+`avatar` names the engenty that stands for the wizard: the one-eyed figure on its pages, in its
+chat and calls, and in the studio’s and marketplace’s lists. It is one of ten shapes:
+
+`round` (the default), `drop`, `dome`, `flame`, `oval`, `bean`, `pebble`, `sprout`, `tower` and
+`wedge`.
+
+The list is fixed. Any other value is an error in the JSON Schema and in `wizards validate`, and
+a wizard cannot bring a picture of its own. Each shape has its own colour.
+
+Every shape is in [`assets/engenty/`](https://github.com/engenty/wizards/tree/main/assets/engenty)
+as a 512 × 512 PNG on a transparent ground. Seven of them also come wearing Goose’s flight
+helmet. The figures are under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): you
+may use, change and share them, commercially too, with credit:
+
+```text
+engenty figures © Thru The Heart Creative GmbH - Matthias Platzer, CC BY 4.0, engenty.ai
+```
+
+Using a figure or the name engenty as your own brand, logo or mascot needs permission. See
+[TRADEMARKS.md](https://github.com/engenty/wizards/blob/main/TRADEMARKS.md).
+
+## Languages
+
+A definition is written in one language, and `lang` names it. Any real language works: `en`,
+`de`, `it`, `fr` and so on. It sets the runner’s own words and how numbers and dates are written.
+The schema checks the shape of the code. `wizards validate` and the studio check that it names a
+real language. Without `lang`, the language is read from the wizard’s own words, and English is
+the default where they are not clearly German.
+
+People who read another language can read the wizard in theirs. The runner offers their
+language, from the browser or the time zone, and translates the wizard on request. AI steps then
+write in that language too. The translation is kept with the wizard in the space, not in the
+definition. These are never translated:
+
+- ids, branches and their `ask` statements
+- the instructions of AI steps and `{{…}}` placeholders
+- the values of choices: a choice shows a translated label and keeps its value
+
+In the studio, Share → Settings has “Offer a translation”. It turns translation on or off for the
+wizard, and each language can be edited line by line there.
+
+## Version
+
+`version` is the version of the format the definition is written in, not of the wizard. It is
+`1` today, and `1` is the default when it is left out.
+
+It changes only with a breaking change to the format. The schemas of each version stay online in
+their own folder (`/schema/v1/`, `/schema/v2/`, …). An app reads only the versions it knows: it
+refuses a wizard of a newer version instead of running it the wrong way.
+
+The versions of a wizard itself, its drafts and what is published, are kept in the studio, not
+in the definition.
+
+## Steps
+
+Every step has an `id`, a `title`, an optional `description` and an optional `next`. Ids are
+letters, digits and `_`, start with a letter and are unique in the wizard. The last step is
+always a `result` step.
+
+| Type | What it does | Page |
+|---|---|---|
+| `page` | Asks the person, one to five fields | [Pages and fields](./pages-and-fields.md) |
+| `agent` | An AI step: researches, writes, decides, calls tools | [Agent steps](./agent-steps.md) |
+| `generate` | Makes an image, a video, a voice-over, a document or a dashboard | [Images, video and documents](./generate-steps.md) |
+| `surface` | Shows a view built from the surface catalog | [Views and widgets](./views-and-widgets.md) |
+| `widget` | Shows an HTML app from the wizard’s workspace | [Views and widgets](./views-and-widgets.md) |
+| `film` | Has the AI client on your computer make a film | [Films](./film-steps.md) |
+| `review` | Shows earlier results to check, change or make again | [Review and result](./review-and-result.md) |
+| `result` | The last page: the message and the downloads | [Review and result](./review-and-result.md) |
+
+Steps run from top to bottom unless a step’s `next` sends the run elsewhere. See
+[Branches and loops](./branches.md). Steps read what came before through templates such as
+`{{topic}}` and `{{steps.post}}`. See [Templates](./templates.md).
+
+## A complete wizard
+
+```json
+{
+  "version": 1,
+  "title": "X post with an image",
+  "description": "Turns a topic into a finished post with an image.",
+  "avatar": "flame",
+  "lang": "en",
+  "steps": [
+    {
+      "id": "about", "type": "page", "title": "What is it about?",
+      "fields": [
+        { "id": "topic", "label": "Topic or occasion", "kind": "textarea", "required": true },
+        { "id": "tone", "label": "Tone", "kind": "select",
+          "options": ["Casual", "Professional", "Funny"], "default": "Casual" }
+      ]
+    },
+    {
+      "id": "post", "type": "agent", "title": "Write the post", "model": "standard",
+      "instructions": "Write a post for X on {{topic}}. Tone: {{tone}}. At most 270 characters.",
+      "tools": [], "output": { "format": "text" }
+    },
+    {
+      "id": "visual", "type": "generate", "title": "Draw the image", "asset": "image",
+      "prompt": "A striking image for this post: {{steps.post}}. No text in the image.",
+      "options": { "aspectRatio": "16:9" }
+    },
+    {
+      "id": "check", "type": "review", "title": "Does this work?",
+      "show": ["post", "visual"], "edit": true, "regenerate": true
+    },
+    {
+      "id": "done", "type": "result", "title": "Ready to post",
+      "deliverables": [
+        { "from": "post", "label": "Post", "formats": ["txt", "md"] },
+        { "from": "visual", "label": "Image", "formats": ["png"] }
+      ]
+    }
+  ]
+}
+```
+
+The studio’s MCP tool `get_authoring_guide` gives an AI client the same format with its rules
+for good wizards.
+
+## Files and checks
+
+- [The .wizard file](./wizard-file.md): what the zip holds and what the import takes.
+- [JSON Schema and validation](./validate.md): the JSON Schema for your editor and `wizards validate`.

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

@@ -0,0 +1,65 @@
+---
+title: Lists and connections
+description: Tables a wizard keeps between runs, and accounts the person connects.
+version: 0.7.10
+---
+
+## Lists
+
+A list is a table the wizard keeps between runs, one for each person who runs it. A wizard has up
+to 12.
+
+```json
+"lists": [{
+  "id": "contacts", "title": "Contacts", "key": "email",
+  "columns": [
+    { "id": "name", "name": "Name", "type": "text" },
+    { "id": "email", "name": "Email", "type": "text" },
+    { "id": "since", "name": "Since", "type": "date", "format": { "kind": "date" } }
+  ]
+}]
+```
+
+| Key | What it does |
+|---|---|
+| `columns` | `id`, `name` (what people read), `type` and `format` |
+| `key` | The column that identifies a row. Saving a row with a known key updates it |
+| `shared` | One list for every run, such as leads or sign-ups |
+| `check` | The person goes through the rows one by one in a review |
+
+Column types are `text`, `number` (`integer`, `decimal`, `percent` or `currency`), `date`
+(`date` or `datetime`), `select` (with `options`) and `boolean`.
+
+Agent steps read and write lists with their own tools. Templates read a list as
+`{{lists.<id>}}`, conditions as `lists.<id>.count`. A `list` field shows it on a page, a review
+shows it with `lists.<id>` in `show`.
+
+A `shared` list is never shown to the person running the wizard, who would see what others gave.
+It shows in the studio under Space → Data.
+
+`check` has `file`, a text column holding the path of a kept file, which shows beside the row. It
+has `status`, a select column whose options are the answers. Its first option means “not looked
+at yet”.
+
+## Connections
+
+A connection is an account the person connects during a run. It is kept for their next run. A
+wizard has up to 12.
+
+```json
+"connections": [
+  { "id": "inbox", "kind": "mail", "title": "Your mailbox" },
+  { "id": "crm", "connector": "hubspot", "actions": ["search_contacts", "create_note"],
+    "policy": { "create_note": "ask" } }
+]
+```
+
+| Key | What it does |
+|---|---|
+| `kind` | `mail`: any mailbox, over Gmail, Outlook or IMAP. Steps only read it |
+| `connector` | Instead of `kind`: a built-in connector or one imported into the space |
+| `actions` | The connector’s actions steps may use. By default those that only read |
+| `policy` | Per action: `allow` runs it, `ask` asks the person first. By default reading is allowed and writing asks |
+
+A page field of kind `connection` asks the person to connect. The agent step lists the connection
+in `connections` and gets its actions as tools.