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.

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:

FileWhat it is
template.json{"contract": "ask@1", "a2ui": "1.0"}. Required.
request.json.j2Renders the data into the request: messages, optional assets and title. Required.
input.schema.jsonA JSON Schema the data must satisfy, checked before anything opens. Without it the data only has to be a JSON object.
submit.schema.json.j2Renders 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.j2Renders the result the caller receives from the data and the action. Without it the result is the action’s context.
snapshot.html.j2Renders the snapshot a host shows for the session. Without it the host’s generic snapshot is used.

Templates are 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.

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:

codeMeaningFields
show_completedan action the template accepted ended the pagecontract, action (name, surface_id, source_component_id, context), result
show_closeda person closed the window, or the session was ended from outsidenone
show_expiredthe attention policy lapsednone

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:

{"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:

{"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:

ItemBound
questions1–8
question textnon-blank, at most 8192 characters
options per question0–32; none requires allow_custom true; at most one recommended
IDs1–64 ASCII letters, digits, underscores or hyphens
option label / descriptionnon-blank label up to 1024 characters; description up to 4096
contextat most 32 blocks; paragraph and code up to 8192 characters; lists of 1–32 items up to 1024
table1–32 columns, up to 128 rows; headings non-blank, cells up to 1024
diffnon-blank, up to 65536 characters
written answerat 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:

{"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.

{"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 rather than a template.