Answer cards
Draft: the closed card (list, metric, camera still, approval pointer) Glyph shows beside a spoken answer.
Living doc, checked against the code 2026-11-14
answer-card.v1 — what the desktop app shows beside a spoken answer
- Status: draft, design only for the four card types (
list,metric,camera_still,approval): no type, frame or renderer exists for them. Live: the render frame, its kinds, the render receipt, the preview door and the brain’spi_show_renderwith card number grounding. - Pattern: json-render. The model fills a closed schema and the client owns the rendering. The brain never sends HTML, CSS, script or a layout.
- Relates to
proactive-card.v1, which says what Vulpine may say unprompted. An answer card is passive: it rides a reply the operator asked for, and it has no verbs.
Why
A spoken answer stays short. A calendar, a camera list or a feed has a list behind it that is tiring to hear in full. The voice says the summary and the panel shows the rest. The spoken reply is the same whether or not anything renders: a frontend without a panel (a room speaker) drops the frame and loses nothing it needs.
The card types (not built)
The design’s four card types and its brain tool pi_show_card are not built. Today a brain shows a list or a metric
as a card.v1 render (panel-card.v1) through pi_show_render.
The render frame
The gateway sends ServerEvent::Render {render_id, kind, data, status, ttl_ms?, turn_id?} only to a frontend that
declared kind.
render_idis minted by the gateway. A later render with the same id replaces the earlier one in place.statusispartial(the body is still growing: draw it and expect more) orcomplete(final, the default).ttl_msis 5 000..=600 000 when present. Absent, the render stays until it is replaced or dismissed.turn_idis the turn of the producer’s open tool call, stamped by the gateway. It is absent for the preview door and the gateway-events bar.
Kinds
RenderComponentKind is a closed, versioned registry. A new kind, or a new version of a kind, is a new variant; a
version never changes in place. The kinds are bar.v1, sparkline.v1, table.v1, line.v1, heatmap.v1,
card.v1 (panel-card.v1), visual.v1, file.v1, page.v1 and links.v1. The last four have
their own contracts. The chart, table and heatmap bodies:
| kind | body | bounds |
|---|---|---|
bar.v1 |
ChartSpec, each series takes values (one bar per series; several values make a group) |
≤ 24 series, ≤ 24 values each |
sparkline.v1 |
ChartSpec, values or points |
≤ 6 series, ≤ 120 points each after downsampling |
line.v1 |
ChartSpec, values or points |
≤ 6 series, ≤ 600 points each after downsampling |
table.v1 |
TableSpec {columns, rows}, plain-text cells, every row as wide as columns |
≤ 12 columns, ≤ 50 rows |
heatmap.v1 |
HeatmapSpec {title? (≤ 80), x_labels, y_labels, cells, unit? (≤ 16)}, cells[row][column], one row per y_labels entry, every row as wide as x_labels |
≤ 48 columns, ≤ 24 rows, ≤ 600 cells |
ChartSpec is {title? (≤ 80), series: [{label (1..=40), points?: [{x, y}], values?: [...]}], unit? (≤ 16)}. A
series has exactly one of points and values. Heatmap labels are 1..=40 characters. Every body refuses unknown
fields, so it carries no color, no HTML and no layout. The theme owns color, and maps a heatmap’s values to a scale.
A text field refuses < and control characters. A number must be finite.
Negotiation and downsampling
A frontend declares the kinds it draws in FrontendCapabilities.render_kinds. The declaration holds for the whole
connection, across start_session. At hello the gateway writes render_kinds_declared {kinds, blocks}: the frame
kinds it kept and the number of block kinds.
For an undeclared kind, or a body that fails its kind, the gateway drops the render and writes
render_dropped {kind, reason}. reason is undeclared or the body’s refusal: shape_mismatch, empty,
over_limit, bad_text, not_finite or bad_envelope. A sent render writes render_sent {kind, points_in, points_out}. No trace row carries a body.
The gateway runs LTTB on a line or sparkline series over its cap before it validates and relays it. LTTB keeps the first and last points and the largest-triangle point of each bucket. A heatmap is never downsampled.
A frontend’s registry maps every kind to a renderer. An unknown kind, or a body of the wrong shape, becomes a fallback
card. Vigil declares bar.v1, sparkline.v1, table.v1, line.v1, card.v1 and page.v1.
The render receipt
A frontend answers each render with the client frame render_receipt {render_id, kind, outcome, reason?}:
outcome:drawn(its renderer drew the body),refused(its registry drew the fallback card) ordropped(it never showed the render).reason:unknown_kind,bad_body,render_failed,bad_envelope(the Client Core refused the envelope) orno_panel. Adrawnreceipt carries no reason.
render_receipt is an additive ClientControl variant. The Client Core sends an additive control only to a gateway
whose hello offers the feature of the same name. Otherwise it drops the control with one control_not_offered
trace per type.
The session’s render router keeps the latest outcome for each of the newest 32 render ids: sent (no receipt yet),
dropped + undeclared, refused + the body’s refusal, or the frontend’s receipt. A receipt for an id not sent on
that connection is refused (unknown_render) and counts nothing. The trace row is render_receipt {render_id, kind, outcome, reason}. Producers read the outcome with RenderRouter::outcome, so a reply never claims a chart that did
not land.
The Admin
The Presentation panel shows a “Render panel” card per connection (AdminPresentationSession.render_routing, an
AdminRenderRouting): the declared kinds, renders sent and dropped since bind, the last render with its age, and
the receipt counts (receipts, optional):
frontend: drawn 3 · refused 1 · dropped 0 — last refused bar.v1 (bad_body)
The line is a warning when the last receipt was not drawn. last_producer (optional) names who drew last, read
from the render id: preview, gateway_events, tool (pi_show_render) or brain (a render with no id). The
Admin validator refuses any other word. calls_closed (optional) counts pi_show_render calls closed with no result
because their turn ended (turn_end) or was cut (turn_cut).
A render the gateway refused (not an undeclared drop), and a refused or dropped receipt, also make a row on the
Admin event timeline: component gateway.render, phase render_refused or render_receipt_refused, with the kind
and the closed reason. Rows are coalesced over a minute for each side.
The gateway-events bar
With [frontend] render_gateway_events = true (default false), the gateway sends a bar.v1 of its Admin event
timeline’s rows per component over the last [frontend] render_gateway_events_minutes (default 15). It sends the bar
when a declaring frontend binds, and again on get_state when the counts changed.
The preview door
vulpine-glyphctl render <kind> --file <body.json> [--ttl <secs>] and vulpine-glyphctl render --sample <kind> post
a render to the gateway’s render_preview door. The gateway answers this invoke_tool itself; it is not a brain
tool. It answers only when [frontend] render_preview = true (default false). --sample sends the Vigil
showcase’s sample body (apps/vigil/src/render/samples.json).
- Input.
{kind, data, ttl_ms?}. The kind must be in the registry. The body is downsampled, then checked against the kind like any producer’s body. A refusal answers with the closed reason. - The board. An accepted preview goes on the preview board as render id
preview, so a later preview replaces it. The calling connection draws it at once when it declared the kind. The post also wakes every bound connection that declared a render kind, which offers the preview at once (trace rowrender_preview_nudged). - The answer. The door answers when a panel’s receipt for the post arrives, from any connection, or after 7 s
without one. Its details carry
this_frontend,receipt(drawn,refused,droppedornone),receipt_reasonandwaited_ms, and its message says it in words (“drawn: a panel drew the bar.v1 preview”). The board keeps the newest receipt per post; a drawn post stays drawn when another panel refuses it. The trace row isrender_preview_answered {kind, seq, receipt, waited_ms}. - The CLI.
vulpine-glyphctl renderprints the receipt word alone on its first line, then the door’s JSON line. It exits 1 on a door refusal or when a panel refused or dropped the render, else 0 (noneis 0).
The brain’s render tool
pi_show_render {kind, body} is a pi_* tool in catalog/pi/extensions/vulpine-tools (show_render.ts). A
loadout allows it per client.
- It sends
show_render {kind, data}over the mutation socket. The socket’s line bound is 8 KiB, and the tool refuses a body over 7 KiB before it sends. - The gateway answers only an open call of this continuity. It parses the kind and the body, mints a render id and
routes the render through the session’s
RenderRouter, like any producer’s render. - A gateway refusal or an
undeclareddrop answers at once. A sent render waits up to 3 s for the panel’srender_receipt. - The answer is
render_shown {kind, outcome, reason, waited_ms}.outcomeisdrawn,refusedordroppedwith the closed reason, orsent+no_receiptwhen the panel never confirmed it. The trace row isshow_render_answered {kind, outcome, reason, waited_ms}. - The tool says “It is on the panel.” only for
drawn. The voice system prompt tells the brain the panel is never spoken: the reply says the answer in words, “on the panel” only fordrawn, the reason and the numbers aloud forrefusedordropped, and no claim forsent+no_receipt.
The brain’s rule prefers card.v1. The chart, table and heatmap kinds also work alone.
Card number grounding
The gateway relays a pi_show_render card only when every number written in its text fields is grounded.
Otherwise it refuses the card, and the spoken reply goes out unchanged. [frontend] card_number_grounding is on by
default; false turns off the check and the grounds. The tool’s description tells the brain: “Restate a tool’s
numbers; never compute new ones in a card.”
- The grounds. The session’s last 16 brain tool results, as they came. From each: every JSON number, every number written in a string, and every array’s length (a list of three hosts grounds “3 hosts”), up to 2 048 numbers and 64 KiB of text. A panel-producing tool’s own panel counts as its result. The card’s own array lengths count too (“Top 3” over three rows).
- The turn’s own words. The prompt the gateway writes to the brain (the operator’s words, the turn and session
context, retrieved evidence, a capture’s block) and every brain tool call’s arguments, except a show-render call’s
own. They sit apart from the 16 results, at most 16 in one turn, and are dropped when the next turn’s prompt starts.
In a prompt, spelled numbers count: zero to nineteen, the tens, and a tens word with a unit word (
twenty-five). A result’s, a call’s or a card’s spelled numbers do not. - Numbers on the card. A digit run that is a word of its own:
3,1234,1,234(commas only between groups of three),12.5,.5, and digits followed by letters (5km,10am,3rd). Not numbers: a word that starts with a letter (v1,Qwen3), a word whose digits resume after its letters (4f9c2ab1), a dotted version (3.11.2), and a list marker (one or two digits that start a line, then.or)and a space:1. Rome). A time or a date is read as its parts (14:30,2026-11-05, an ISOT). An hour followed bypmalso stands for the 24-hour hour, and12 amstands for 0. The sign is ignored. - Rounding. A written number stands for anything that rounds to it at its written precision:
12.5for 12.45 to 12.55,3for 2.5 to 3.5. An integer of four or more digits counts trailing zeros as rounding and keeps at least two significant digits:12,000stands for 11 500 to 12 500. Ak/K,m/M,b/B/bnsuffix, orthousand/million/billionafter one space, stands for the scaled value (1.2kfor 1 150 to 1 250). A%also stands for the fraction (60%for 0.595 to 0.605). A decade (a round number of tens from 20 withs:80s,mid-90s) stands for its ten (80sfor 80 to 90). - Durations. A number with
msalso stands for its seconds; withsec,secs,secondorseconds, for its minutes. A result’s number under a key naming the unit (ackMs,timeout_ms,timeout_s,waitSeconds) grounds the next unit too. - Which fields are read. Every string, except links and references (
link,url,href,sha256,frame_ref,ref), templates and scripts (template,data,script,svg), block type tags (type), and axis and header labels (x,x_labels,y_labels,columns). A card’svalue(aPanelValue) is read in both its forms, except a threshold’s and a breakdown part’s numbers-onlyvalue. Numbers-only data fields are not read: series values, heatmap cells, compare, forecast, delta and share numbers. Afile.v1is not read. - The refusal. The check runs after the body parses and before the render is routed. The brain’s answer is
render_shown {outcome: refused, reason: unsupported_number, at}, whereatis the first field that failed (blocks.0.tiles.1.value). Nothing reaches the panel. The trace rows arecard_refused {kind, reason, at, numbers, results, words, us}andshow_render_answered. A grounded card writescard_grounded {kind, numbers, results, words, us}. No row carries the card’s text or the number. The Admin event timeline gets one warning row,gateway.render/card_refused, coalesced over a minute. - What is refused. A number the brain derives: a sum, a difference, a unit conversion, a relative time (“3 minutes ago” from an epoch stamp) or a time-zone shift. The brain can restate the card from the tool’s own numbers.