@engenty/wizards-runtime 0.7.11 → 0.9.0

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.

package/apps/runtime/dist/docs/dev/wizard-format/meta.json

@@ -0,0 +1,19 @@
+{
+  "title": "The wizard format",
+  "pages": [
+    "index",
+    "validate",
+    "wizard-file",
+    "---Steps---",
+    "pages-and-fields",
+    "agent-steps",
+    "generate-steps",
+    "views-and-widgets",
+    "film-steps",
+    "review-and-result",
+    "---Across steps---",
+    "templates",
+    "branches",
+    "lists-and-connections"
+  ]
+}

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

@@ -0,0 +1,102 @@
+---
+title: Pages and fields
+description: A page step and its fields, the field kinds, and fields that show only when they fit.
+version: 0.7.10
+---
+
+A `page` step asks the person. It holds at least one field, and a good page has at most five.
+`cta` is the button’s label.
+
+```json
+{
+  "id": "about", "type": "page", "title": "What is it about?", "cta": "Write it",
+  "fields": [
+    { "id": "topic", "label": "Topic", "kind": "textarea", "required": true,
+      "placeholder": "e.g. We open our new studio on Friday", "help": "For the first line" },
+    { "id": "tone", "label": "Tone", "kind": "select",
+      "options": ["Casual", "Professional"], "default": "Casual" }
+  ]
+}
+```
+
+A field’s `id` is unique in the whole wizard, because later steps read the answer by it. Every
+field has a `label` and a `kind`, and may have `required`, `placeholder`, `help` and `default`.
+
+## Field kinds
+
+| Kind | What the person gives | Keys of its own |
+|---|---|---|
+| `text`, `textarea` | A line, or a few paragraphs | `scan` (text): fill it from a QR code or barcode |
+| `number`, `date`, `email`, `url` | A number, a date, an address, a link | |
+| `select`, `multiselect` | One or several of `options` | `optionsFrom`, `cards` |
+| `toggle` | Yes or no | |
+| `color` | A colour | |
+| `image` | Photos, taken or uploaded | `multiple`, `min`, `max` (up to 30) |
+| `file` | Documents, photos, recordings | `multiple`, `min`, `max`, `camera`, `video`, `listen` |
+| `items` | Line items with totals | `columns`, `vat`, `currency` |
+| `location` | Where they are, or an address they type | |
+| `audio` | A voice note of up to 5 minutes, written down before the next step | |
+| `signature` | A signature drawn with the finger | |
+| `slot` | One appointment time, shown by day | `options` or `optionsFrom`, as ISO 8601 date-times |
+| `connection` | Connects one of their accounts | `connection`: the id of a wizard connection |
+| `list` | Checks and corrects a stored list | `list`: the id of a wizard list |
+
+## Line items
+
+An `items` field takes positions and computes the totals itself:
+
+```json
+{ "id": "positions", "label": "Positions", "kind": "items", "currency": "EUR",
+  "vat": { "rate": 20 },
+  "columns": [
+    { "id": "what", "label": "Service", "kind": "text" },
+    { "id": "hours", "label": "Hours", "kind": "number" },
+    { "id": "rate", "label": "Rate", "kind": "money" }
+  ] }
+```
+
+A row’s amount is the product of its `number` and `money` columns. `vat.field` reads the rate
+from another field instead. Documents take the table with its totals from `{{positions}}`. See
+[Templates](./templates.md).
+
+## Answers from earlier steps
+
+- `prefill` (`"steps.<id>.<key>"`): what the field starts with. An `items` field takes a table
+  whose columns are its column ids, and the person corrects the rows.
+- `optionsFrom`: the choices of a `select`, `multiselect` or `slot` come from earlier data. It
+  names a list output (`steps.<id>.<key>`), a column of a table output
+  (`steps.<id>.<key>.<column>`) or a column of a stored list (`lists.<id>.<column>`). `options`
+  stand in while that data is empty.
+- `cards`: with `optionsFrom` naming a table output, each row is a card. Its keys name the
+  table’s columns: `label`, `value` (default: the label), `image`, `subtitle`, `meta` and `link`.
+
+## Fields that show only when they fit
+
+`when` shows a field only while a condition holds. It reads a field of the same page, decided as
+the person types, or anything known before the page:
+
+```json
+{ "id": "company", "label": "Company", "kind": "text",
+  "when": { "field": "customerType", "op": "equals", "value": "Business" } }
+```
+
+A hidden field is not asked and not kept. Its template is empty. Conditions are described on
+[Branches and loops](./branches.md#conditions).
+
+Where no rule on one field can say it, a decision picks the fields as the run reaches the page:
+
+- `ask` on a field: a statement. The field shows when the decision finds it true of the run,
+  for example “The complaint is about a damaged article”.
+- `groups` on the page and `group` on fields: of a group’s fields the decision shows one. With
+  `optional`, it may show none.
+
+```json
+"groups": [{ "id": "reach", "instructions": "How should we reach the person?" }],
+"fields": [
+  { "id": "phone", "label": "Phone", "kind": "text", "group": "reach" },
+  { "id": "mail", "label": "Email", "kind": "email", "group": "reach" }
+]
+```
+
+A page with decided fields holds up to 12 fields and shows at most 5. A field has `ask` or
+`group`, not both.

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

@@ -0,0 +1,64 @@
+---
+title: Review and result
+description: A review step shows earlier results to check, the result step ends the run with its downloads.
+version: 0.7.10
+---
+
+## Review
+
+A `review` step shows what earlier steps made. The person accepts it, changes it or asks for a
+new version.
+
+```json
+{
+  "id": "check", "type": "review", "title": "Does this work?",
+  "show": ["post", "visual"], "edit": true, "regenerate": true
+}
+```
+
+| Key | What it does |
+|---|---|
+| `show` | The step ids whose results are shown, or `lists.<id>` for a stored list |
+| `edit` | The person may change text results directly |
+| `regenerate` | The person may ask for a new version, with a note |
+
+A shown list is edited in place. A list with `check` goes row by row on a split screen. See
+[Lists and connections](./lists-and-connections.md#lists).
+
+Put a review before anything expensive, such as video, and before anything written elsewhere,
+such as a mail or a CRM.
+
+## Result
+
+The `result` step is always the last. It shows `message` and offers the downloads.
+
+```json
+{
+  "id": "done", "type": "result", "title": "Ready to post",
+  "message": "Copy the text and download the image.",
+  "deliverables": [
+    { "from": "post", "label": "Post", "formats": ["txt", "md"] },
+    { "from": "visual", "label": "Image", "formats": ["png"] }
+  ]
+}
+```
+
+Each deliverable names a step id or `lists.<id>` in `from`, an optional `label` and its
+`formats`.
+
+## Formats
+
+| From | Formats |
+|---|---|
+| `generate` image | `png` |
+| `generate` video | `mp4`, `zip` for several results |
+| `generate` voice | `mp3` |
+| `generate` document | `pdf`, `docx`, `html`, `md`, `png` |
+| `generate` dashboard | `html`, `pdf`, `png` |
+| `widget` | `html`, `png`, `pdf`, `json`, and `mp4` when the widget has a timeline |
+| `widget` with `video` | `mp4`, `png` |
+| `film` | `mp4` |
+| `agent` with `text` or `markdown` | `md`, `txt`, `docx`, `pdf`, `html` |
+| `agent` with `json` | `json`, `csv`, `xlsx` (a sheet per table), `md`, and `pdf` with a `schema` |
+| `agent`, any format | `zip`: the files the step kept |
+| `lists.<id>` | `xlsx`, `csv`, `json`, `md`, and `zip` for a list with `check.file` |

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

@@ -0,0 +1,57 @@
+---
+title: Templates
+description: How instructions, prompts and briefs read answers, earlier results, the space and stored lists.
+version: 0.7.10
+---
+
+Instructions, prompts and briefs are templates. `{{…}}` is filled in when the step runs:
+
+```text
+Write a post for X on {{topic}}. Tone: {{tone}}. Use these facts: {{steps.research}}
+```
+
+A template may only name fields asked and steps run earlier. `wizards validate` says when one
+does not.
+
+## What a template reads
+
+| Template | What it gives |
+|---|---|
+| `{{fieldId}}` | The answer to a field |
+| `{{steps.stepId}}` | A step’s whole result |
+| `{{steps.stepId.key}}` | One key of a `json` step’s result |
+| `{{lists.listId}}` | A stored list as a table, as it is when the step starts |
+| `{{today}}` | Today’s date |
+| `{{brand.name}}`, `{{brand.about}}`, `{{brand.colors}}` | The space’s brand |
+| `{{facts.key}}`, `{{facts}}` | One fact of the space, such as its address or VAT ID, or all of them |
+
+Every AI step already knows the brand and the facts. Name one only where the text must carry it.
+
+## Fields with more than one value
+
+| Template | What it gives |
+|---|---|
+| `{{itemsField}}` | The line items as a table with net, VAT and total |
+| `{{itemsField.net}}`, `.vat`, `.gross` | One of the totals |
+| `{{fileField}}` | The names of the uploads |
+| `{{field.speech}}` | A `file` field with `listen`: what is said, piece by piece with times |
+| `{{audioField}}`, `{{audioField.seconds}}` | What the person said, and how long |
+| `{{locationField}}` | The address with its position, for example “Herrengasse 16, Graz (47.07071, 15.43950, ±12 m)” |
+| `.lat`, `.lng`, `.accuracy`, `.label`, `.map` | One part of a location, `.map` a map link |
+| `{{signatureField}}` | The picture as `asset://ID`, for `<img src="asset://ID">` in a document |
+
+Documents take `{{itemsField}}` as it is. The runner computes the totals, never a model.
+
+## Inside a step with `each`
+
+| Template | What it gives |
+|---|---|
+| `{{item.column}}` | One column of the current entry |
+| `{{index}}` | The number of the entry |
+| `{{count}}` | How many entries there are |
+
+## References outside templates
+
+Other keys name the same things without braces: `prefill`, `optionsFrom`, `each`, a widget’s or
+surface’s `data` and a condition’s `field`. They take `fieldId`, `steps.<id>`, `steps.<id>.<key>`
+and `lists.<id>`, as each key’s page says.

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

@@ -0,0 +1,63 @@
+---
+title: JSON Schema and validation
+description: The JSON Schema for your editor, and wizards validate for everything a schema cannot say.
+version: 0.7.10
+---
+
+## JSON Schema
+
+| For | Schema |
+|---|---|
+| A definition | [`https://engenty.ai/schema/v1/wizard.json`](https://engenty.ai/schema/v1/wizard.json) |
+| `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`.
+
+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.
+
+## `wizards validate`
+
+```bash
+wizards validate invoice.wizard
+```
+
+It checks a wizard the way the studio’s import does, without a running studio and without an
+account. It also 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.
+
+It takes any number of paths:
+
+| Path | Read as |
+|---|---|
+| `invoice.wizard` | A package |
+| `invoice/` or `invoice/wizard.json` | An unpacked package, its workspace under `invoice/files/` |
+| `invoice.json` | A definition on its own, or a `wizard.json` |
+
+```text
+✗ invoice.json 2 issues
+  The last step must be a result step.
+  "{{nope}}" refers to a field that is not asked before "g".
+```
+
+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.
+
+## In CI
+
+```bash
+npx wizards validate wizards/*.wizard
+```
+
+`npx wizards` installs engenty wizards into `~/.engenty/wizards` first, the first time. To check
+without an install, on Node.js 24.11 or newer, run the runtime from npm directly:
+
+```bash
+npx -p @engenty/wizards-runtime wizards validate wizards/*.wizard
+```
+
+What belongs to a space is checked only on import. See
+[What the import takes](./wizard-file.md#what-the-import-takes).

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

@@ -0,0 +1,103 @@
+---
+title: Views and widgets
+description: Surfaces built from the catalog, a view of an agent step's result, nested output, and HTML widgets.
+version: 0.7.10
+---
+
+A result can show as a view instead of a plain table. There are three ways:
+
+| Way | What it is | Costs per run |
+|---|---|---|
+| A `surface` step | A view built from the surface catalog, written once | Nothing |
+| `output.surface` on an agent step | The same, bound to that step’s own result | Nothing |
+| A `widget` step | An HTML app in the wizard’s workspace, written once | Nothing |
+
+Choose a surface for facts, a list of results, key figures or a chart. Choose a widget for what
+the catalog cannot show, such as a map or an animation.
+
+## Surfaces
+
+A surface is a flat array of components. The one with id `root` is drawn, and containers list
+their children by id. A prop is a value, or `{ "path": "/key/…" }` into the data.
+
+```json
+{
+  "id": "show", "type": "surface", "title": "Your offers",
+  "data": { "offers": "steps.research.offers" },
+  "components": [
+    { "id": "root", "component": "Column", "children": ["head", "list"] },
+    { "id": "head", "component": "Text", "text": "Three offers for you", "variant": "lead" },
+    { "id": "list", "component": "List", "children": { "path": "/offers", "componentId": "row" } },
+    { "id": "row", "component": "Row", "title": { "path": "name" }, "meta": { "path": "price" } }
+  ]
+}
+```
+
+`data` maps keys to what the surface reads: a field id, `steps.<id>`, `steps.<id>.<key>`,
+`lists.<id>`, `brand.name` or `today`.
+
+| Components | For |
+|---|---|
+| `Column`, `Grid`, `Tabs`, `Fold`, `Group` | Layout: stacks, tiles, two to four views, details on a tap, entries under a heading per value |
+| `Text`, `Callout`, `Badge`, `DetailGrid`, `Metric` | Words, a tip or warning, a label, facts, a key figure |
+| `Card`, `List`, `Row`, `Link` | Things: one card per thing, rows, an entry that opens in a sheet |
+| `Chips`, `Checklist`, `Steps` | Short things, things to get or do, ordered work |
+| `Table`, `BarChart`, `LineChart`, `DonutChart` | Figures compared across columns, charts |
+| `Image`, `Actions`, `Button` | A picture, buttons that make the result again or open it |
+
+`candidates` replaces `components` when the view should change per run. Each candidate is a piece
+with a `description`, and a decision picks the pieces that fit: no chart when there is nothing to
+chart. `group` and `groups` work as on [pages](./pages-and-fields.md#fields-that-show-only-when-they-fit),
+and `required` pieces always show.
+
+The MCP tool `get_authoring_guide` lists every component with its props.
+
+## A view of an agent step’s result
+
+An agent step with `output.format` `json` can carry its own view in `output.surface`, bound to
+its keys by path. Reviews and the result show it in place of a table. `output.surface: true` has
+a model compose a view on every run instead, which costs a model call.
+
+For nested data, `output.schema` replaces `output.fields`. Its root is an object:
+
+```json
+"schema": { "kind": "object", "label": "Menu plan", "fields": {
+  "days": { "kind": "list", "label": "Days", "of": { "kind": "object", "label": "Day", "fields": {
+    "label": { "kind": "text", "label": "Day" },
+    "recipe": { "kind": "ref", "label": "Recipe", "to": "recipes" } } } },
+  "recipes": { "kind": "list", "label": "Recipes", "of": { "kind": "object", "label": "Recipe", "fields": {
+    "id": { "kind": "text", "label": "ID" },
+    "minutes": { "kind": "number", "label": "Time", "unit": "min" } } } } } }
+```
+
+Kinds are `text` (with `long` for paragraphs), `number` (with `unit`), `yesno` (with `yes` and
+`no`, the words people read), `choice`, `ref` (the id of an entry of a top-level list) and `list`.
+Objects nest at most four deep, with a hundred keys in all. Labels are in the wizard’s language.
+The view is checked against the schema.
+
+## Widgets
+
+A `widget` step shows an HTML page from the wizard’s workspace. It is written once, and every run
+only brings new data.
+
+```json
+{
+  "id": "map", "type": "widget", "title": "The route",
+  "entry": "route/index.html", "sample": "route/sample.json",
+  "data": { "stops": "steps.plan.stops" },
+  "size": { "width": 1280, "height": 720 }
+}
+```
+
+| Key | What it does |
+|---|---|
+| `entry` | The workspace path of the HTML |
+| `data` | What the page gets as `wizard.data`: key → a field id, `steps.<id>`, `steps.<id>.<key>`, `brand.name` or `today` |
+| `sample` | Example data in the same shape, for previews before any run |
+| `layout` | `fixed` (the default): drawn at `size` and scaled to the page. `page`: part of the page, as tall as its content |
+| `size` | The design size, 200 to 3840 px. The default is 1280 × 720. PNG, PDF and MP4 render at it |
+| `video` | The result is a film: the timeline is rendered to an MP4 with sound |
+
+The page loads nothing from the network when it runs. Libraries and reference data are files in
+the workspace. It talks to the runner through `window.wizard`: `data`, `brand`, `ready()`,
+`timeline()`, `state` and `save()`, among others.