# Show a person a page from your data

`afui show` renders a **template** from the data you give it and puts the page in
front of one person. The page is A2UI 1.0. The person acts on it, the template
decides which action is the answer, and one result comes back.

```sh
afui show ask --data '{"questions":[{"id":"next","question":"What should happen next?","options":[{"id":"retry","label":"Retry","recommended":true},{"id":"stop","label":"Stop"}]}]}'
```

Two templates are built in. `ask` is the standard question page (below). `a2ui`
takes A2UI messages exactly as you wrote them and shows them. Anything else is
a template of your own.

## What a template is

A template is a directory:

| File | What it is |
| --- | --- |
| `template.json` | `{"contract": "ask@1", "a2ui": "1.0"}`. Required. |
| `request.json.j2` | Renders the data into the request: `messages`, optional `assets` and `title`. Required. |
| `input.schema.json` | A JSON Schema the data must satisfy, checked before anything opens. Without it the data only has to be a JSON object. |
| `submit.schema.json.j2` | Renders a JSON Schema from the data; an action the page sends back must satisfy it, or it is refused and the page stays open. Without it every action is accepted. |
| `result.json.j2` | Renders the result the caller receives from the data and the action. Without it the result is the action's `context`. |
| `snapshot.html.j2` | Renders the snapshot a host shows for the session. Without it the host's generic snapshot is used. |

Templates are [MiniJinja](https://docs.rs/minijinja). In the JSON files every
`{{ value }}` is written as one complete JSON value, quoted and escaped as JSON
needs, so what the data says cannot add structure to the output: write
`"text": {{ title }}`, not `"text": "{{ title }}"`. A name the data does not
define is an error. Test for one with `is defined`. The snapshot is HTML and
escapes what it prints.

What a template renders is checked like a request written by hand: it must be
A2UI 1.0 messages that follow the schemas, with images and sizes inside the
limits. A template can do exactly what a caller writing A2UI directly could.

### The contract

`contract` is `<name>@<number>`: lowercase letters, digits and `-`, then a
positive integer. It describes what the template takes (`input.schema.json`) and
gives back (`result.json.j2`), not its directory name, so a copy that only
changes the layout can keep declaring `ask@1`. The result of `afui show` names the
contract it came from, and `--expect-contract ask@1` refuses a template that
declares another, before anything opens.

`a2ui` is the A2UI version the messages are written for. This build renders `1.0`
and says so in `afui --version`. A template declaring another version is refused
with `a2ui_version_unsupported`, which names both.

### Where a name is found

`afui show NAME` looks in the workspace's `.afui/templates/NAME`, then in the
global configuration's `templates/NAME`, then among the presets. **The first
place with a directory by that name supplies all of it**: files are never mixed
between places, so a template that leaves out an optional file does not pick up
the preset's.

A workspace template is another person's checkout until someone trusts it. It is
used only after `afui template enable NAME`, and any change to any file in it
withdraws that; until then `afui show` fails with `template_untrusted` rather
than quietly showing something other than what was asked. A global template is the
user's own configuration and needs no enabling. `--safe-mode` uses the
presets only. `--template-dir PATH` uses that directory as given, with no lookup
and no trust step, because it is exactly as trusted as the data you pass.

```sh
afui template list                          # what can be named
afui template init polite-ask --from ask    # copy a template to start from
afui template check polite-ask              # contract, A2UI version, trust
afui template enable polite-ask             # trust the workspace copy as it is now
afui template diff polite-ask               # workspace against global
afui template disable polite-ask
```

`init` copies a whole template into the workspace (`--scope global` for the global
configuration). The copy is yours: it does not follow the preset when AFUI
changes.

## Data, delivery and results

`--data` takes the data as literal JSON, `file:PATH` (the whole file), `stdin`,
`fd:N` or `env:NAME`; `file:PATH#DOT_PATH` reads one addressed value. Sources are
capped at 16 MiB and a rendered request at 1 MiB. Relative image paths resolve
from the working directory.

`--mode window|link|session` uses the delivery resolver, including
`AFUI_LAUNCH_FILE`. A `session` page requires a writable session registry.

`--render` prints the rendered request and stops: nothing opens, no credential is
issued. What it prints is the input of the `a2ui` template, so
`afui show ask --data ... --render | afui show a2ui --data stdin` shows the same
page. `--render` cannot be combined with `--mode` or `--detach`.

The readiness progress event has `phase: "show_ready"`, the contract, the session
ID and the resolved delivery facts. It never carries the data. Only link delivery
publishes its handoff URL, through the existing readiness helper.

The terminal result:

| `code` | Meaning | Fields |
| --- | --- | --- |
| `show_completed` | an action the template accepted ended the page | `contract`, `action` (`name`, `surface_id`, `source_component_id`, `context`), `result` |
| `show_closed` | a person closed the window, or the session was ended from outside | none |
| `show_expired` | the attention policy lapsed | none |

All three are successful interactions (exit 0). Taking a cancel button is just
another action: the caller reads `action.name`. Setup, validation and transport
failures are structured errors with exit 1; CLI grammar errors keep exit 2.

The error codes say which part is at fault: `template_*` for the template itself
(`template_not_found`, `template_untrusted`, `template_invalid`,
`template_render_failed`, `template_contract_mismatch`), `data_invalid` for data
the input schema refuses, with a JSON Pointer `path` and never the value, and
`a2ui_*` for what the template rendered (`a2ui_message_invalid` with the path of
the fault, `a2ui_asset_unreadable`, `a2ui_request_too_large`, and so on).
`submit_invalid` is the refusal shown to the person on the page; it names the
place in the submitted action, never the text.

### The session ends when the template accepts an action

The page sends actions and data to AFUI's Provider; the Provider decides whether
that is enough. For `afui show`, the Provider is the template: the first action
that satisfies `submit.schema.json.j2` (or any action, when there is none) ends
the session, and the page closes. A refused action leaves the page open with the
reason, so the person can correct it.

### Waiting without holding a command open

`afui show` blocks until the page ends. A caller whose commands have a time limit
uses `--detach`: the page runs in a background process and the command returns as
soon as it is ready. The data goes to the worker over stdin, never argv, and the
worker reads every image before reporting readiness, so after `show_started` the
source files may be removed:

```json
{"kind":"result","result":{"code":"show_started","mode":"session","session_id":"4181c256…"},"trace":{}}
```

`afui session wait <session_id>` returns the terminal result `afui show` would
have printed. With `--timeout-s N` it stops after N seconds and reports
`show_pending` with `waiting_s`, the page still open. Omit the flag or use `0` to
wait until it ends; negative values are CLI errors. A result is collected once:
a later wait returns `show_not_found`. The worker records its ending in an
owner-only directory beside the session registry, so `--detach` is refused with
`show_detach_unavailable` when that registry cannot be opened. The worker leaves the caller's process group, so a caller that kills
its command on timeout does not take the page with it. AFUI does not remind the
person: it does not know where they are.

Window failures keep AFUI's error kind with a `show_` prefix: a nonzero or
signal exit is `show_window_wait_failed`, and a successful exit without a page
request carrying this launch's query ID is `show_window_unavailable`. A
successful exit after the page arrived is `show_closed`, which supplies no result
and implies no consent.

## The `ask` template

An agent often needs a person's answer to a few questions, each with suggested
answers, while leaving room for something the list did not anticipate. `ask`
owns that interaction: background context, one to eight questions, one answer
per question. It displays evidence for a judgment and collects choices and text.
Domain operations, dynamic forms and sustained interaction belong in a template
of your own or a Provider page. Nothing the person answers is ever executed, and
the page renders no Markdown or HTML.

The data is `context` (optional) and `questions`:

```json
{"context":[
  {"type":"paragraph","text":"The review found two issues."},
  {"type":"table","columns":["ID","Status"],"rows":[["A","Ready"]]}
],"questions":[
  {"id":"scope","question":"Which should be fixed?","multiple":true,
   "options":[{"id":"readme","label":"README"},{"id":"subject","label":"Subject","description":"The session subject"}]},
  {"id":"when","question":"When to release?","allow_custom":false,
   "options":[{"id":"now","label":"Now","recommended":true},{"id":"later","label":"Later"}]}
]}
```

An option has a stable `id`, a human `label`, an optional `description` and an
optional `recommended` flag. A question has an `id`, the `question` text, its
`options`, optional `multiple` (several choices) and optional `allow_custom`
(default `true`). Context blocks are `paragraph {text}`, `list {items}`,
`code {text}`, `image {path,title}`, `table {columns,rows}` and `diff {text}`.
Images are local PNG, JPEG or WebP files with matching signatures, up to 16 of
8 MiB and 32 MiB in all; URLs and SVG are refused, and the page gets a
controlled reference, never a local path.

The input schema holds these bounds, and unknown fields and block types are
refused:

| Item | Bound |
| --- | --- |
| questions | 1–8 |
| question text | non-blank, at most 8192 characters |
| options per question | 0–32; none requires `allow_custom` true; at most one `recommended` |
| IDs | 1–64 ASCII letters, digits, underscores or hyphens |
| option label / description | non-blank label up to 1024 characters; description up to 4096 |
| context | at most 32 blocks; paragraph and code up to 8192 characters; lists of 1–32 items up to 1024 |
| table | 1–32 columns, up to 128 rows; headings non-blank, cells up to 1024 |
| diff | non-blank, up to 65536 characters |
| written answer | at most 16384 characters |

A schema cannot say that IDs are unique or that every table row is as long as
its columns, so those are left to whoever writes the request; a repeated ID makes
the result ambiguous.

The page shows the context, then the questions. A single-choice question takes one
option or the person's own words, never both; a multiple-choice question may
combine them. Recommended options are marked in their label and never
preselected. Written text is kept exactly as typed, and blank text counts as no
answer. A submission that does not satisfy that is refused with the place of the
fault and the page stays open. Cancel needs no answers.

The result of a submitted `ask` page:

```json
{"kind":"result","result":{"code":"show_completed","contract":"ask@1",
 "action":{"name":"submit","surface_id":"ask","source_component_id":"submit","context":{"answers":[]}},
 "result":{"cancelled":false,"answers":[
  {"question_id":"scope","selected":[{"option_id":"readme","label":"README"}],"text":"Also check the skill"},
  {"question_id":"when","selected":[],"text":null}
 ]}},"trace":{}}
```

`selected` lists the chosen options with their labels, in the order chosen, and
`text` is the person's own words, `null` when they wrote none. A cancelled page has
`{"cancelled":true,"answers":[]}`. The registry subject of a page is the first
line of its first question, shortened to 80 characters.

## The `a2ui` template

`afui show a2ui --data` takes `messages` (A2UI 1.0 messages), optional `assets`
(names to local image paths, referenced as `asset:<name>` in an Image's `url`) and
optional `title` (what the host calls the page, 1–80 characters). With no submit
schema the first action ends the session and the result is its context.

```json
{"messages":[
  {"version":"1.0","createSurface":{"surfaceId":"main","catalogId":"https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json"}},
  {"version":"1.0","updateComponents":{"surfaceId":"main","components":[
    {"id":"root","component":"Column","children":["label","button"]},
    {"id":"label","component":"Text","text":"Ready?"},
    {"id":"button","component":"Button","child":"button-label","action":{"event":{"name":"done"}}},
    {"id":"button-label","component":"Text","text":"Done"}
  ]}}
],"title":"Review"}
```

The page renders the Basic Catalog: Text (with `#` headings), Image, Icon, Video,
AudioPlayer, Row, Column, List, Card, Tabs, Divider, Modal, Button, TextField,
CheckBox, ChoicePicker, Slider and DateTimeInput, with the Basic Catalog's
functions (`required`, `regex`, `length`, `numeric`, `email`, `and`, `or`, `not`,
`formatString`, `formatNumber`, `formatCurrency`, `formatDate`, `pluralize`,
`openUrl`). Schema errors name a JSON Pointer without echoing the rejected value.
External media is blocked. A reload starts a fresh draft. Presentation overrides
follow the `afui` / `show` frontend contract and cannot supply behavior.

A Rust program serving A2UI itself uses [`A2uiSession`](https://agentfirstkit.com/agent-first-ui/docs/providers.md#a2ui-sessions-messages-actions-and-functions)
rather than a template.
