kestrel.markets/docs/public/first-frame.md

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

# First Frame — perception

Before an author can decide anything, it has to *see*. Perception in Kestrel is three nouns
in a line: a **View** says what should be seen, a **Frame** is that View materialized at one
moment, and a **Rendering** is one serialization of a Frame. This page teaches the three and
the one rule that makes them trustworthy: **a Rendering never invents a value.**

## A View is what should be seen

A View is the standing definition of what should be seen — which panes, at what token
budget. It is a spec, not a picture; it never computes. Every value it displays arrives in
the Frame.

```kestrel id=frame-view check=roundtrip
VIEW open budget 1800
  tape skyline 5m vwap
  levels registry
  chain fair realness
```

This View selects four **panes** — a tape skyline over a 5-minute window with VWAP, a levels
table from the registry, and a chain card showing fair value and its realness — under a
budget of 1800 tokens. A **pane** is one named block within a View; a chart is one kind of
pane, not the general term.

## A Frame is a View materialized at one moment

The terminal is live video; a **Frame** is one instant of it, fully specified — the typed
bundle of values, each carrying its source. Replay is just a sequence of Frames.

- A full Frame is a **keyframe** (the OPEN screen).
- A **delta frame** carries only what changed since the author's last Frame (the WAKE
  screen) — so a long-running agent perceives at O(new bars), not O(whole screen).

Part of every Frame is the **kernel** — the non-configurable part, bound to the session. An
*acting* session (a Book or Pod attached) carries positions, resting orders, budget, and the
wake reason; a *spectator* Frame (nothing at stake) carries only provenance — watermarks,
as-of, data health. You cannot opt out of the acting kernel by editing the View. An agent
never trades blind to its own inventory because the kernel is not yours to remove.

## A Rendering never invents a value

A **Rendering** is one serialization of a Frame. It chooses only glyphs, layout, and token
spend — a format (`ascii · unicode · md · json · html`) and the tokenizer its costs are
measured under. The agent's ASCII screen and the human's HTML chart are two Renderings of
**one Frame**: same numbers, same moment. This is the load-bearing invariant — a Rendering
never invents or changes a value. That is what lets a human and an agent trust that they are
looking at the same reality.

## What is real today

Keep the axes separate (this is the whole discipline of the [capability
truth](./capability-truth.md) page). The `VIEW` statement above **parses and round-trips**
today — its syntax is supported and CI proves it. How far the runtime that materializes a
View's pane selection into a live Frame has been wired is graded on its own *runtime* axis;
read the honest state on the [status page](./status.md) rather than assuming syntax implies
execution.

## Next

- **[First Plan](./first-plan.md)** — now that you can see, decide: a bounded-risk contingent
  program.
- **[The shared lexical core](./lexical-core.md)** — the series and expressions a View shares
  with the other three statement kinds.