kestrel.markets/docs/public/overview.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.

# What Kestrel is

Kestrel is a typed, token-efficient **language and runtime for agentic trading**. The
agent authors; the runtime perceives and executes. Everything an author writes is one of
**four statement kinds** over **one lexical core** — and the same text is truth for a human
reading a chart, a program composing typed objects, and an agent emitting a plan.

This page is the on-ramp. It says what the four kinds are and how they divide labor, then
hands you to the four "first" pages that each teach one kind, the [shared lexical
core](./lexical-core.md), and [how to read what Kestrel actually claims](./capability-truth.md).

## Prove it in one command

Before the concepts, the smoothest front door — zero credential, zero config, zero file:

```bash
npx kestrel.markets prove
```

Bare `prove` picks a pinned default free scenario, runs it against the hosted anonymous
trial, and prints the graded story plus a shareable proof URL — no key, no config, no prompt.
It runs a bundled starter strategy, so the grade is a real, filled trade (graded honestly,
small losses included), never dressed up as alpha. Author your own with
`npx kestrel.markets prove --plans <file>`. That is the whole cold start; the rest of this
page is the language behind it.

Every claim in these pages is *graded*, not asserted: [Capability Truth](./capability-truth.md)
explains how to read a capability's status honestly across four independent axes — where the
certified cohort is still 0.

## One language, four statement kinds

A single grammar with one lexical core carries four kinds of statement. Each answers a
different question:

| Kind | Question | Lifecycle | Spends |
| --- | --- | --- | --- |
| **View** | *What should I see?* | standing | attention |
| **Wake** | *When should I look?* | standing | attention |
| **Plan** | *What may execute?* | standing | **risk** |
| **Grade** | *Did it actually work?* | imperative | compute |

View, Wake, and Plan are **standing**: authored, armed, versioned, and superseded, acting
over time. Grade is **imperative**: a job that runs, terminates, and returns a result — it
is never armed. Only a Plan can spend risk; View and Wake spend only attention (tokens and
wakes), and a Grade only reads recorded history.

## The division of labor

The whole system is a split between slow judgment and fast reflex:

- **The agent authors.** It is smart but slow, so it never sends orders. It writes
  statements — a View of what to watch, a Wake for when to look, a Plan for what may fire.
- **The runtime perceives and executes.** It materializes Views into Frames (the renderer
  is live; wiring a VIEW statement's pane selection into it is [in progress](./status.md)),
  evaluates triggers on every tick, and fires armed Plans at machine speed —
  **fire-then-inform**: it acts first and wakes the author in parallel, never instead.
- **Risk sits above both.** A bounded-risk envelope can clamp or veto anyone, including the
  agent, and may never *open* risk.

Slow judgment, compiled into a fast reflex.

## The smallest complete Plan

A Plan is a standing, bounded-risk contingent program. Here is the minimum: a name, a risk
budget, a time-to-live, a trigger, and one action.

```kestrel id=overview-plan check=roundtrip
PLAN first-plan budget 0.2R ttl +30m
  WHEN spot crosses above hod
  DO buy 1 +1 C @ min(fair, mid)
```

Read it as one sentence: *for the next 30 minutes, risking at most 0.2R, when spot crosses
above the high of day, buy one call one strike out — but never pay more than fair value.*
The [First Plan](./first-plan.md) page unpacks every clause.

## Where to go next

One "first" page per kind, in the order the four are introduced above — perception, then
attention, then risk, then result — followed by the core they share and how to read what is
real:

- **[First Frame](./first-frame.md)** — **View**: perception. A Frame is a View materialized
  at one moment; a Rendering never invents a value.
- **[First Wake](./first-wake.md)** — **Wake**: attention. A standing subscription over the
  trigger algebra that decides *when* to look and delivers a View — never risk.
- **[First Plan](./first-plan.md)** — **Plan**: risk. A bounded-risk contingent program:
  trigger → actions → bracket → invalidation → TTL, fired then informed.
- **[First Grade](./first-grade.md)** — **Grade**: result. The honest result of a run — did
  the judgment actually work? — graded, never asserted.
- **[The shared lexical core](./lexical-core.md)** — the one lexical core all four kinds
  share (series, the trigger algebra, price expressions, lexical conventions).
- **[Capability truth](./capability-truth.md)** — how to read the four-axis catalog and the
  [status page](./status.md): what parses vs. what runs vs. what has evidence vs. where it is
  reachable.

Every Kestrel example above and on the pages that follow is extracted from this source and
run through the real parser and printer in CI (see [grammar-fences](./grammar-fences.md)) —
prose that contains syntax is a claim, and a claim that no longer parses is caught.