---
title: "Answer cards"
description: "Draft: the closed card (list, metric, camera still, approval pointer) Glyph shows beside a spoken answer."
type: "living"
source: "docs/contracts/answer-card.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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's `pi_show_render` with 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`](/docs/contracts/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`](/docs/contracts/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_id` is minted by the gateway. A later render with the same id replaces the earlier one in place.
- `status` is `partial` (the body is still growing: draw it and expect more) or `complete` (final, the default).
- `ttl_ms` is 5 000..=600 000 when present. Absent, the render stays until it is replaced or dismissed.
- `turn_id` is 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`](/docs/contracts/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) or `dropped` (it
  never showed the render).
- `reason`: `unknown_kind`, `bad_body`, `render_failed`, `bad_envelope` (the Client Core refused the envelope) or
  `no_panel`. A `drawn` receipt 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 row `render_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`, `dropped` or `none`),
  `receipt_reason` and `waited_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 is
  `render_preview_answered {kind, seq, receipt, waited_ms}`.
- **The CLI.** `vulpine-glyphctl render` prints 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 (`none` is 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 `undeclared` drop answers at once. A sent render waits up to 3 s for the panel's
  `render_receipt`.
- The answer is `render_shown {kind, outcome, reason, waited_ms}`. `outcome` is `drawn`, `refused` or `dropped` with
  the closed reason, or `sent` + `no_receipt` when the panel never confirmed it. The trace row is
  `show_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 for `drawn`, the reason and the numbers aloud for
  `refused` or `dropped`, and no claim for `sent` + `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 ISO `T`). An hour followed by `pm` also stands for the
  24-hour hour, and `12 am` stands for 0. The sign is ignored.
- **Rounding.** A written number stands for anything that rounds to it at its written precision: `12.5` for 12.45 to
  12.55, `3` for 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,000` stands for 11 500 to 12 500. A `k`/`K`, `m`/`M`, `b`/`B`/`bn` suffix, or
  `thousand`/`million`/`billion` after one space, stands for the scaled value (`1.2k` for 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 with `s`: `80s`,
  `mid-90s`) stands for its ten (`80s` for 80 to 90).
- **Durations.** A number with `ms` also stands for its seconds; with `sec`, `secs`, `second` or `seconds`, 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's `value` (a `PanelValue`) is read in both its
  forms, except a threshold's and a breakdown part's numbers-only `value`. Numbers-only data fields are not read:
  series values, heatmap cells, compare, forecast, delta and share numbers. A `file.v1` is 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}`, where `at` is the first field that failed
  (`blocks.0.tiles.1.value`). Nothing reaches the panel. The trace rows are `card_refused {kind, reason, at, numbers,
  results, words, us}` and `show_render_answered`. A grounded card writes `card_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.

