Panel cards
The panel card (card.v1) the brain or a tool fills: one composite of a title, a spoken one-line summary, an optional headline number and one to four typed blocks (stats, list, chart, table, heatmap, timeline, progress, status, compare, breakdown, forecast, text), their bounds, the refusals with the path the brain must fix, the fallback ladder (an undeclared block as text, a table projection), the render frame's appended turn_id, and what the Admin shows.
Living doc, checked against the code 2026-11-14
panel-card.v1 — the panel the brain or a tool fills, drawn in the conversation
- Status: landed on protocol 5, additive. The kind
card.v1, its bodyCardSpecand the block kinds below are in the protocol crate. The gateway validates, bounds, degrades and projects cards; the brain’spi_show_rendersends them, and some tools fill their own panels. - Scope: the brain (through
pi_show_render) or the tool that already holds the numbers fills one JSON card. The gateway checks it and relays it as therenderframe, stamped with the turn it belongs to. Each frontend draws it with its own renderer. No HTML, no server-side rendering, no pictures, no colors, no layout, no URLs. - Relates to
answer-card.v1: its render frame is the transport, and its closed schema is the model. A card is passive: it rides a reply and has no verbs.
What the brain fills
A card is one constrained composite with fixed slots, drawn in this order: a header (title, subtitle, a status
flag), an optional headline number, one to four typed blocks, and a footer note. Panels vary the blocks, not
the frame, so the brain learns one shape.
summary is the one line the reply says aloud whether or not a panel draws anything. It is also the card’s
accessible name, the conversation log’s caption and the text fallback. Plain words, never an id or a hex token.
CardSpec, the body of card.v1
| field | type | bound | required |
|---|---|---|---|
title |
string | 1..=80, no hex token | yes |
subtitle |
string | ≤ 80 | no |
summary |
string | 1..=160, no hex token | yes |
flag |
{text, state} |
text 1..=24 | no (the header’s right-hand flag) |
headline |
{value, unit?, delta?, delta_unit?, better?, caption?} |
unit ≤ 16, delta_unit ≤ 8, caption ≤ 60 | no (the big number) |
blocks |
array of blocks | 1..=4, drawn in order | yes |
note |
string | ≤ 120 | no (the footer’s provenance line) |
Every text field refuses < and control characters, and a required one refuses blank text. Every number is finite.
Every object refuses an unknown field. The card-wide budget is 720 numbers and cells across the headline and all
blocks (series values, heatmap and table cells, tiles, rows, items, steps, parts; a compared row and a forecast day
count two). The brain tool’s 7 KiB body cap also applies on its path.
Shared values
| type | wire | rule |
|---|---|---|
PanelValue |
a number or a string | a finite number, or text 1..=24 ("1m 42s"), sent only when the value is not a number. The client formats numbers |
| unit | string | 1..=16 ("ms", "%", "°C", "$"). $ € £ are drawn before the number, any other unit after it |
delta, delta_unit, better |
number, string ≤ 8, up or down |
the change, its unit (default the value’s unit), and which direction is good (default up), so a chip is tinted good or bad, not up or down |
PanelState |
ok warn bad idle active pending done failed skipped |
one closed set for every block; the theme maps it |
Sky |
clear partly cloudy fog drizzle rain snow sleet storm wind |
a forecast day’s icon key; the frontend owns the icons |
ChartMark |
bar line area step |
how a chart block draws |
The blocks (PanelBlockKind, internally tagged by type)
The block kinds are a second closed registry, versioned like the frame kinds; a version is never changed in place.
table.v1 and heatmap.v1 reuse the frame kinds’ bodies, so a frontend that draws those kinds draws those blocks.
| block | body | bounds |
|---|---|---|
text.v1 |
{text} |
1..=280. The degrade target every card client must draw |
stats.v1 |
{tiles: [{label, value, unit?, delta?, delta_unit?, better?, of?, caption?, state?}]} |
1..=6 tiles; label ≤ 40, caption ≤ 40; of > 0 makes the tile a meter (value of max) |
list.v1 |
{rows: [{label, detail?, value?, unit?, delta?, state?, share?}], more?} |
1..=12 rows; label ≤ 60, detail ≤ 80; share 0..=1 draws an inline bar; more draws “and N more” |
chart.v1 |
{mark, x?, series: [{label, values}], unit?, stacked?, threshold?: {value, label?}, band?: {from, to, label?}, highlight?, forecast_from?} |
1..=6 series, every series as long as the others (and as x when given), 1..=120 values each after the gateway’s downsampling; x labels ≤ 16; stacked for bar and area only; band.from ≤ band.to; highlight and forecast_from are indexes into the values |
table.v1 |
{columns, rows} |
inside a card: 1..=6 columns, 1..=12 rows, cells ≤ 80 |
heatmap.v1 |
{title?, x_labels, y_labels, cells, unit?} |
as the heatmap.v1 kind (≤ 48 × 24, ≤ 600 cells), within the card budget |
timeline.v1 |
{items: [{at, label, detail?, state?}], now_after?} |
1..=12 items in the order given; at 1..=24 (a display time: "09:30", "Tue 14:00"); label ≤ 60, detail ≤ 80; now_after is the index after which the NOW line is drawn |
progress.v1 |
{steps: [{label, state, detail?}], done?, total?} |
1..=12 steps; label ≤ 40, detail ≤ 40; total ≥ the steps shown, done ≤ total (“3 of 12”) |
status.v1 |
{items: [{label, state, value?, detail?}]} |
1..=24 items (a grid); label ≤ 32, detail ≤ 40 |
compare.v1 |
{a_label, b_label, rows: [{label, a, b}], unit?, better?} |
column labels 1..=24, 1..=12 rows of finite numbers |
breakdown.v1 |
{parts: [{label, value}], unit?, total?} |
1..=8 parts, each ≥ 0; total ≥ their sum (else the sum). The producer folds the rest into “other” |
forecast.v1 |
{unit, days: [{label, sky, high, low, precip_pct?}]} |
1..=10 days, label ≤ 12, unit 1..=4 ("°C"); high ≥ low; precip_pct 0..=100 |
template.v1 |
{template, text, data, svg?} |
a curated template’s block, behind the gateway’s [panels] templates flag (off); see template.v1 |
Examples (synthetic)
A forecast card (what the weather tool would send):
{"title": "Week ahead", "subtitle": "five days", "summary": "Mild and dry until Thursday, then rain on Friday.",
"flag": {"text": "rain Fri", "state": "warn"},
"headline": {"value": 18, "unit": "°C", "delta": 3, "better": "up", "caption": "high today, warmer than yesterday"},
"blocks": [{"type": "forecast.v1", "unit": "°C", "days": [
{"label": "Mon", "sky": "clear", "high": 18, "low": 7},
{"label": "Tue", "sky": "partly", "high": 21, "low": 9},
{"label": "Wed", "sky": "cloudy", "high": 19, "low": 8},
{"label": "Thu", "sky": "drizzle", "high": 15, "low": 5, "precip_pct": 40},
{"label": "Fri", "sky": "rain", "high": 16, "low": 6, "precip_pct": 80}]}],
"note": "forecast · updated 06:00"}
One block of each kind (each is one entry of a card’s blocks):
{"type": "text.v1", "text": "Latency is flat almost everywhere; two windows stand above the limit at the same hours each day."}
{"type": "stats.v1", "tiles": [
{"label": "memory", "value": 61, "unit": "%", "of": 100, "state": "ok"},
{"label": "disk free", "value": 212, "unit": "GB", "delta": -14, "better": "up"},
{"label": "uptime", "value": "6d 4h"}]}
{"type": "list.v1", "rows": [
{"label": "Water the plants", "detail": "due today", "state": "warn"},
{"label": "Return the library book", "detail": "due Friday"},
{"label": "Order filters", "detail": "overdue 2 days", "state": "bad"}], "more": 4}
{"type": "chart.v1", "mark": "bar", "x": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
"series": [{"label": "steps", "values": [6100, 7400, 5200, 9800, 8800, 12100, 4300]}],
"unit": "steps", "threshold": {"value": 8000, "label": "goal"}, "highlight": 5}
{"type": "chart.v1", "mark": "line", "x": ["Mon", "Tue", "Wed", "Thu", "Fri"],
"series": [{"label": "high", "values": [18, 21, 19, 15, 16]}, {"label": "low", "values": [7, 9, 8, 5, 6]}],
"unit": "°C", "forecast_from": 1}
{"type": "table.v1", "columns": ["worktree", "state"], "rows": [["main", "clean"], ["lane-a", "2 uncommitted"]]}
{"type": "heatmap.v1", "x_labels": ["06", "09", "12", "15", "18", "21"], "y_labels": ["Mon", "Tue", "Wed"],
"cells": [[0, 2, 5, 3, 1, 0], [1, 4, 6, 2, 2, 1], [0, 1, 3, 4, 2, 0]], "unit": "updates"}
{"type": "timeline.v1", "items": [
{"at": "09:00", "label": "Planning", "state": "done"},
{"at": "11:30", "label": "Walk", "state": "active"},
{"at": "14:00", "label": "Review", "detail": "45 min"},
{"at": "17:30", "label": "Dinner"}], "now_after": 1}
{"type": "progress.v1", "steps": [
{"label": "build", "state": "done", "detail": "4 min"},
{"label": "review", "state": "active"},
{"label": "test", "state": "pending"}]}
{"type": "status.v1", "items": [
{"label": "host one", "state": "ok", "value": "load 2.4"},
{"label": "host two", "state": "ok", "value": "load 3.1"},
{"label": "host three", "state": "bad", "detail": "not answering"}]}
{"type": "compare.v1", "a_label": "last week", "b_label": "this week", "unit": "h", "better": "up",
"rows": [{"label": "sleep", "a": 6.8, "b": 7.3}, {"label": "focus", "a": 18, "b": 15}]}
{"type": "breakdown.v1", "unit": "agents", "parts": [
{"label": "busy", "value": 7}, {"label": "awaiting input", "value": 3}, {"label": "done, unseen", "value": 2}]}
The brain may leave the version off a block type: the tool stamps a bare type with its current version (status
becomes status.v1). The wire is always versioned. An unknown bare type is left as written, for the gateway to
refuse:
{"kind": "card.v1", "body": {"title": "Fleet right now", "summary": "Two hosts are up and one is not answering.",
"blocks": [{"type": "status", "items": [{"label": "host one", "state": "ok"}, {"label": "host two", "state": "ok"},
{"label": "host three", "state": "bad", "detail": "not answering"}]}]}}
The frame
A card rides the render frame, with one optional field appended:
{"type": "render", "render_id": "render-7", "kind": "card.v1", "status": "complete", "ttl_ms": 300000,
"turn_id": "00000000-0000-4000-8000-0000000000a1", // appended, optional
"data": { /* CardSpec */ }}
The gateway stamps turn_id, never the producer: a render from pi_show_render carries the turn its call was made
in. The preview door and the gateway-events bar carry none. The conversation log places a panel under its turn; a
frame without one binds to the turn in flight. The Client Core relays it as RenderFrame.turnId (null when
absent), and the native client crate as RenderFrame.turn_id.
Negotiation and the fallback ladder
A frontend lists the frame kinds and the block kinds it draws in render_kinds. Unknown names are ignored, so an
older gateway ignores the block ids. The gateway then sends a card:
- to a frontend that declared
card.v1, with each block whose kind it did not declare replaced by atext.v1block holding that block’s one-line text (panel_block_text: stats → “memory 61 %, disk free 212 GB, uptime 6d 4h”; a list → its first three labels and “and N more”; a chart → each series’ last value; progress → “review active, 1 of 3 done”; and so on, at most 160 characters). The trace rowrender_sentgainsblocksanddegraded; - else to a frontend that declared
table.v1, as atable.v1projection under the same render id (card_table: two columnsitemandvalue, a row for the headline, then each block’s rows, at most 50). The trace row isrender_projected {from, to}, and the frontend’s receipt speaks for the table; - else nowhere:
render_dropped {reason: undeclared}, as for any kind. Nothing is lost: the reply says the summary.
Downsampling: a line, area or step chart block with no x and 121 to 600 values per series is reduced to
120 by LTTB. The kept positions are chosen on the first series and every series keeps the same ones; highlight
and forecast_from move to the kept position at or before theirs. A bar block, or any series with x, over 120 is
refused.
Errors
The gateway refuses a card before relay with one of the closed render refusals and where, a path of field names and indexes joined by dots, so the brain can fix its body:
| refusal | example | at |
|---|---|---|
over_limit |
five blocks | blocks |
over_limit |
more than 720 numbers and cells | blocks |
empty |
no blocks | blocks |
bad_text |
a hex token in the summary | summary |
bad_text |
markup in the title | title |
shape_mismatch |
x shorter than the series |
blocks.0.x |
empty |
a list with no rows | blocks.1.rows |
shape_mismatch |
an unknown block type (the body does not parse) | blocks.2.type |
shape_mismatch |
an unknown field in a block | blocks.0.color |
over_limit |
a share over 1, a high under the low, an index past the values | blocks.0.rows.1.share, blocks.0.days.2.low, blocks.0.highlight |
not_finite |
a NaN in a Rust producer’s series | blocks.0.series.0.values.3 |
pi_show_render’s answer is render_shown {kind, outcome, reason, waited_ms, at?, projected_to?, degraded?}:
at on a refused card; projected_to: "table.v1" when the card reached a panel as its table; degraded when one
or more blocks reached it as text. The tool says “It is on the panel.” only for drawn (“It is on the panel, as a
table.” for a projection). Each refusal case has a file in benchmarks/fixtures/panel-card.v1/invalid/.
The brain has one pi_show_render call open at a time. It closes when the brain’s turn ends or is cut, as a
producer’s call does, so a result that never came does not block later panels. A panel already sent stays until its
ttl_ms. A late show_render from the closed call is refused as brain_tool_call_or_continuity_mismatch. The close
is a show_render_call_closed trace row and an Admin timeline row. close_turn_tool_calls in
crates/voice_gateway/src/ws/state/lifecycle.rs closes every per-turn call at the turn’s end and at its cut. The
Render card counts the closed pi_show_render calls (AdminRenderRouting.calls_closed).
Panels the tools fill
A tool that already holds the numbers builds its own card and puts it up with no pi_show_render call. The brain
spends no tokens on it, and the numbers never pass through the model. The producers are a closed list in the gateway
(PANEL_PRODUCER_TOOLS in crates/voice_gateway/src/routing.rs):
| tool | card | built from |
|---|---|---|
pi_utility (weather) |
“Next N days”: a forecast.v1 block of up to five days (open-meteo’s weather codes mapped to Sky, highs and lows rounded, the rain chance), today’s reading as the headline, a flag for storms or a day of 50 % rain or more. With no forecast asked, “Weather now”: the reading as the headline and a stats.v1 block (the sky, the wind) |
the open-meteo answer the tool already fetched |
pi_fleet_status |
“Fleet right now”: a stats.v1 block (waiting on you, busy, finished unseen, errors) and a status.v1 grid of the hosts, worst first (bad for an agent in error or a failed CI run, warn for one waiting on the operator, active, done, ok) |
the gateway’s own fleet snapshot |
brain_vulpine_report |
Per topic: “Reply time by hour” (a chart.v1 of the median and 90th percentile per hour, the slowest hour highlighted, and a stats.v1 block); “Nightly, list.v1 of the suites that did not pass); “What went wrong”, “Connections”, “Vulpine health”, “What gets used” (stats.v1 with a list.v1 or status.v1) |
the card the gateway builds in crates/voice_gateway/src/vulpine_report.rs and answers over the Admin socket; the tool relays it unchanged |
pi_house_now |
“House now”: a stats.v1 block, a status.v1 grid of the rooms and a timeline.v1 of recent camera events, with a flag when home is unknown or a camera stalled |
the house document the gateway answered (catalog/pi/extensions/vulpine-tools/house_now.ts) |
pi_feeds (unread) |
“Unread in your feeds”: a links.v1 panel of the items the tool listed (the title, the feed; at most 12, “and N more” for the rest), the tool’s counts as the summary. A frontend that does not declare links.v1 gets it as a card.v1 list. The titles are the sites’ own words, drawn as plain text and never sent back to the brain |
the feedctl answer the tool already read (catalog/pi/extensions/vulpine-tools/feeds.ts, feeds_links.ts) |
pi_github (stars, repo_read) |
“Your recent stars”: a list.v1 of the newest stars (the name, the language and description, how long ago). A starred repo: stats.v1 (files, folders, stars, README words), its top folders as a list.v1, its language mix as a breakdown.v1 and its description as a text.v1. The tool’s other actions send no card |
the gh api answers the tool already read (catalog/pi/extensions/vulpine-tools/github/stars.ts) |
The builders are catalog/pi/extensions/vulpine-tools/panels.ts (GitHub’s in
catalog/pi/extensions/vulpine-tools/github/stars.ts). Their cards from synthetic inputs are in
benchmarks/fixtures/panel-card.v1/tools/.
- One panel per open call. When the brain calls a producer, the gateway registers the call with the turn it was
made in. While the call is open it accepts ONE
show_renderline on the mutation socket under that call’s id (the same linepi_show_rendersends), stamps the call’s turn on the frame, and routes it like any card. A second panel from the call, a panel after the tool answered or after the brain’s turn ended, a call of another continuity, and any tool off the list are refused asbrain_tool_call_or_continuity_mismatch. At most four producer calls are open at once. - Never in the way. The gateway answers a producer’s panel at once with where it went (
sent,dropped+undeclared, orrefusedwith the reason andat), never on the panel’s receipt. The tool waits at most 750 ms for that word. The tool’s own answer is the same with or without a panel. A brain with no mutation socket gets no panel. The panel’s receipt reaches the router and the Admin row when it comes. - What the brain is told. The tools’ descriptions and the voice prompt’s
pi_show_renderline say they put their own card up. The brain never sends a second one for the same numbers, and says the answer in words as usual. - One card per subject per turn. An older forecast card never shows beside the current one. A card whose subject
an earlier card of the same turn already showed goes out under that card’s render id, and every frontend replaces
the older card in place (
crates/voice_gateway/src/render_subject.rs; trace rowrender_replaced {subject}). The subjects are closed: only the forecast (a card carrying aforecast.v1block). Another turn’s card, a card with no subject and a render bound to no turn keep their own ids. A frontend receipts a complete body that replaces a different complete body of the same id (the Glyph look’s panel stack; Vigil receipts every frame), so the brain’s call hearsdrawn.
template.v1: a curated template’s block
A block can be a curated panel template (ADR 0045): a
folder under catalog/panels/ holding a Typst template.typ, its schema.json, a
sample.json and a README. A new panel is a folder, not a block kind plus a builder plus a renderer per client. The
producer names the template and fills its data. It never writes markup and never sends a drawing.
| field | type | bound | who fills it |
|---|---|---|---|
template |
string | [a-z][a-z0-9-]*, ≤ 40: the folder’s name |
the producer |
text |
string | 1..=160, no hex token: the block’s accessible name and its degrade line | the producer |
data |
object | the template’s schema.json (a closed JSON Schema subset), the card’s text rule on every string, the card’s budget |
the producer |
svg |
{dark, light, width, height} |
each drawing ≤ 384 KiB, one inert <svg> (no script, foreign object, handler or outside link); sides 1..=2000 pt |
the gateway: a producer’s own svg is refused at blocks.N.svg |
The gateway, with [panels] templates = true:
- checks the block’s shape with the card (
validate_card_at: the name, the line, an object fordata); - checks
dataagainst the template’s schema, refusing with the card’s closed reasons and where:blocks.0.data.days.2.color(shape_mismatch, a field the schema does not name),blocks.0.data.counts.busy(over_limit),blocks.0.data.hosts(empty),blocks.0.data.hosts.1.detail(bad_text). An unknown template, a template’s ownassertor any compile fault isshape_mismatchatblocks.N.template, and a missed deadline isover_limitthere; - for a frontend that declared
template.v1, compiles the template with the data in the sandbox (crates/panel_templates: the folder and the kit in memory, no file system, no network, no clock, a deadline), once per scheme with the panel kit’s dark and light tokens, and fillssvg. A frontend that did not declare it gets the block astext.v1holdingtext(degrade_card), as for any undeclared block.
With the flag off (the default) a template block is refused at blocks.N.type. The trace rows are
render_template_compiled {template, compile_ms, cached, svg_bytes} and render_template_refused {template, reason, detail} (the compiler’s word, never the data). A client draws the scheme its look asks for as an image (the panel
kit: porcelain the light drawing, the other looks the dark one), never as inline markup. Vigil and Glyph draw it
but do not declare it by default (UNDECLARED_BY_DEFAULT; Vigil’s ?declare=template declares it).
The forecast and fleet panels are templates too (catalog/panels/forecast, catalog/panels/fleet-status), with their
cards in benchmarks/fixtures/panel-card.v1/templates/. The tools send the native blocks.
Which frontends get panels
pi_show_render is allowed in the loadouts that any frontend with a screen binds: vigil.toml (Vigil binds vigil
by default), laptop.toml and loadout.toml, the default loadout. A frontend that binds default and declares no render kinds (a satellite, the TUI) gets the tool’s “the panel here
cannot show that” answer at once.
Vigil draws cards with the panel kit. Its hello declares card.v1 and its block kinds by default
(VIGIL_DECLARED_KINDS in apps/vigil/src/render/registry.tsx); ?declare=card changes nothing. The table.v1 and
heatmap.v1 blocks share their ids with the frame kinds whose bodies they reuse, so declaring the heatmap block also
declares the heatmap frame kind. Vigil leaves heatmap.v1 out by default, and a card’s heatmap block reaches it as
its one line of text. ?declare=heatmap declares both. Vulpine.app’s Glyph look declares card.v1 and the block
kinds the panel kit draws (GLYPH_RENDER_KINDS in apps/glyph/src/panels/draw.tsx).
Compatibility
- The protocol stays version 5.
RenderComponentKind::Card,RenderData::CardandServerEvent::Render.turn_idare appended. The TypeScript bindings are generated by ts-rs. - An older frontend never declares
card.v1, so it never gets a card; one that declaredtable.v1gets the projection. An older Vigil that gets one anyway keeps the kind a string and draws its fallback card. - An older gateway sends no
turn_id; the Client Core readsnull. PanelBlock::Template,TemplateBlockandTemplateSvgare appended (the thirteenth block kind,template.v1). An older frontend never declares it, so it gets the block’s line. An older gateway refuses a template block (blocks.N.type, an unknown block type).- An older gateway answers
pi_show_render {kind: "card.v1"}withrefused+unknown_kind. The tool’s answer parse accepts the new fields only in their exact shapes. - The Admin’s render row names frame kinds only:
card.v1counts there like any kind, withlast_kind: card.v1even when the card went as its table. Block ids never enterAdminRenderRouting.kinds: the Admin validator refuses a name the frame registry does not know.
The Admin
The Admin draws no card. A card moves the Presentation section’s “Render panel” counters like any render: sent or
dropped, the receipts, the last kind (card.v1), its producer (tool for pi_show_render and for a tool’s own card
alike) and its outcome. A refused card is an event-timeline row (gateway.render, render_refused) with the closed
reason. So is a pi_show_render call closed at its turn’s end with no result (gateway.render,
show_render_call_closed). The “Render panel” block counts those closes since the frontend bound, in amber:
“calls closed with no result: 2 at turn end · 1 cut — last 4s ago” (calls_closed {turn_end, turn_cut, last_at_ms} on
the row, absent until the first close).