@engenty/wizards-runtime 0.7.11 → 0.9.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/integration/index.md

@@ -29,7 +29,7 @@ other systems, from a plain link to a chat that starts the wizard by itself.
 
 | | |
 |---|---|
-| [Your own UI](./own-ui.md) | Your app draws the run with `@engenty-wizards/runner` |
+| [Your own UI](./own-ui.md) | Your app draws the run with `@engenty/wizards-runner` |
 | [Results to your systems](./results.md) | What a run produces goes on to your own systems |
 
 Each way starts from a published wizard. [Test and share](../../user/test-and-share.md) in the

package/apps/runtime/dist/docs/dev/integration/openui.md

@@ -148,7 +148,7 @@ the wizards it may start and a proxy to the runtime. In short:
    Each one’s token is the part of its link after `/w/`.
 2. Put an `.env.local` in `examples/openui-chat`: `WIZARDS=<token>,<token>`, `CHAT_BASE_URL`,
    `CHAT_API_KEY` and `CHAT_MODEL` for the chat’s model.
-3. `pnpm --filter @engenty-wizards/example-openui-chat dev` and open `http://localhost:5190`.
+3. `pnpm --filter @engenty/wizards-example-openui-chat dev` and open `http://localhost:5190`.
 4. Ask for something a wizard does, in your own words.
 
 The example’s README has the details, the endpoints that work and what to set while you try

package/apps/runtime/dist/docs/dev/integration/own-ui.md

@@ -1,10 +1,10 @@
 ---
 title: Your own UI
-description: Draw a wizard’s run in your own app with @engenty-wizards/runner and the runtime’s public run routes.
+description: Draw a wizard’s run in your own app with @engenty/wizards-runner and the runtime’s public run routes.
 version: 0.7.4
 ---
 
 This page is not written yet.
 
 Until then, [OpenUI](./openui.md) shows one app that does it: it draws the run with
-`@engenty-wizards/runner` (`packages/runner`) over the runtime’s public run routes.
+`@engenty/wizards-runner` (`packages/runner`) over the runtime’s public run routes.

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/plugins/examples.md

@@ -1,7 +1,7 @@
 ---
 title: Examples
 description: Two plugins in the repository to read, run and copy.
-version: 0.5.0
+version: 0.8.0
 ---
 
 The repository has two example plugins. Load them from a checkout with one line in `.env.local`:
@@ -75,8 +75,7 @@ node scripts/build-plugin.mjs examples/plugins/run-log --watch
 Then, in the studio:
 
 1. Test a wizard to its end.
-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
+2. Open the space’s Results with the tray icon in the app bar. “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.

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

@@ -1,7 +1,7 @@
 ---
 title: The studio half
 description: Pages, icons in the app bar, sections of the settings and of the space page – written in React, built once, drawn inside the studio.
-version: 0.5.0
+version: 0.8.0
 ---
 
 The studio half is `ui/plugin.tsx`. Its default export is a function; the studio calls it after
@@ -10,7 +10,7 @@ same router, the same components.
 
 ```tsx
 import { defineStudioPlugin } from "@engenty/wizards/plugin/studio";
-import { Button, Card, Empty, Spinner } from "@engenty-wizards/web/ui";
+import { Button, Card, Empty, Spinner } from "@engenty/wizards-studio/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { Users } from "lucide-react";
 
@@ -268,12 +268,11 @@ studio.useCrumbs([{ label: t("title"), to: "/contacts" }, { label: person.name ?
 ## A page with a menu
 
 A page with parts of its own puts its menu where the studio’s own pages put theirs. `MenuPage`
-from `@engenty-wizards/web/ui` draws the menu in the studio’s sidebar while that is open, and at
-the page’s left otherwise, so there is only ever one menu at the left. `PageMenu` draws the menu
+from `@engenty/wizards-studio/ui` draws the menu at the page’s left. `PageMenu` draws the menu
 as the settings do: a list with one level below it, and tabs on a phone.
 
 ```tsx
-import { MenuPage, PageMenu } from "@engenty-wizards/web/ui";
+import { MenuPage, PageMenu } from "@engenty/wizards-studio/ui";
 import { useParams } from "react-router";
 
 function ContactsPage() {
@@ -338,7 +337,7 @@ there is one React and one router on the page:
 | `react-dom` | `createPortal`, `flushSync` |
 | `react-router` | `Link`, `NavLink`, `Navigate`, `useNavigate`, `useParams`, `useLocation`, `useSearchParams` |
 | `@tanstack/react-query` | `useQuery`, `useMutation`, `useQueryClient` |
-| `@engenty-wizards/web/ui` | The studio’s components, see [Styles and components](./styling.md) |
+| `@engenty/wizards-studio/ui` | The studio’s components, see [Styles and components](./styling.md). The earlier name `@engenty-wizards/web/ui` still works |
 | `@engenty/wizards/plugin/studio` | `defineStudioPlugin` and the types |
 
 Everything else a plugin imports is bundled into `client.js`. A package the plugin’s folder

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

@@ -1,7 +1,7 @@
 ---
 title: Styles and components
 description: The studio's components, Tailwind against the studio's theme, and why a plugin's styles never leak.
-version: 0.5.0
+version: 0.8.0
 ---
 
 A plugin’s page should look like the studio. Two things make that easy: the studio’s components
@@ -9,7 +9,7 @@ and its theme.
 
 ## Components
 
-`@engenty-wizards/web/ui` is what the studio itself is drawn with:
+`@engenty/wizards-studio/ui` is what the studio itself is drawn with:
 
 | Component | For | Props beside the element’s own |
 |---|---|---|
@@ -28,7 +28,7 @@ and its theme.
 | `DateRangePicker` | A day or a period in one month: the first click is the start, the second the end | `from`, `to`, `onChange({ from, to })`, `min`, `max` |
 | `TimePicker` | A time of day from an hour and a minute column; arrow keys on the field move it by `step` | `value` (“HH:MM” or “”), `onChange`, `step` (minutes, default 5), `compact` (narrow, no clock) |
 | `PageMenu` | A page’s own menu: a list at the side with one level below that slides in, tabs on a phone | `title`, `entries` ({ id, label, icon?, to, entries? }), `current`, `footer` |
-| `MenuPage` | A page with a menu of its own: the menu stands at the page’s left, or in the studio’s sidebar while that is open, so there is only ever one menu at the left | `menu` (a `PageMenu`, or any), `children` (the page) |
+| `MenuPage` | A page with a menu of its own: the menu stands at the page’s left | `menu` (a `PageMenu`, or any), `children` (the page) |
 | `Composer` | The field a message is written in: text, dictation, files, send | `onSend(text, files)` (false keeps the draft), `placeholder`, `disabled`, `attach`, `floating` |
 | `Dialog` | A modal; on a phone it fills the screen | `open`, `onClose`, `title`, `wide` (`true`, or `"page"` for a document), `height="tall"` (for tabs, folds or lists: its height does not jump), `bare` (the children are the panel) |
 | `Spinner`, `Empty` | Loading, and nothing there yet | |
@@ -45,7 +45,7 @@ and its theme.
 | `newId()` | A short id for something new | |
 
 ```tsx
-import { Button, Card, Chip, Label, Input } from "@engenty-wizards/web/ui";
+import { Button, Card, Chip, Label, Input } from "@engenty/wizards-studio/ui";
 
 <Card className="flex flex-col gap-4 p-5">
   <Label hint="Where the message goes.">Address</Label>
@@ -57,11 +57,14 @@ import { Button, Card, Chip, Label, Input } from "@engenty-wizards/web/ui";
 </Card>
 ```
 
+A plugin written against the earlier name, `@engenty-wizards/web/ui`, still builds: the build
+maps both names to the same components.
+
 Icons are from `lucide-react`.
 
-Most of these components live in the runner package (`@engenty-wizards/runner`), so a wizard’s
-run page looks like the studio. Import them from `@engenty-wizards/web/ui` all the same: that is
-the import the studio shares. `@engenty-wizards/runner` is not shared, so the build would bundle
+Most of these components live in the runner package (`@engenty/wizards-runner`), so a wizard’s
+run page looks like the studio. Import them from `@engenty/wizards-studio/ui` all the same: that is
+the import the studio shares. `@engenty/wizards-runner` is not shared, so the build would bundle
 it into `client.js`.
 
 ## Tailwind

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.