---
title: "Contracts overview"
description: "The versioned wire and file shapes, one file per contract; a breaking change is a new file."
type: "living"
source: "docs/contracts/README.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

The versioned wire and file shapes: one file per contract. A breaking change is a new file.

A file is named `<name>.v<N>.md` and titled `# <name>.v<N> — <what crosses the boundary>`; the docs site shows
each one under a reader's name instead. Most wire types live in `crates/protocol`; a contract names its types and
the code that speaks it.

## What is here

| file | what |
|---|---|
| [`acp-integration.v1.md`](/docs/contracts/acp-integration.v1) | acp-integration.v1 — accepted design for ACP role, capability, authority and lifecycle contract; no runtime activation |
| [`hc-terminal-rpc.v1.md`](/docs/contracts/hc-terminal-rpc.v1) | hc-terminal-rpc.v1 — the terminal attachment an ACP agent needs from hc (private prototype, off in both gateway roles) |
| [`acp-provider-registry.v1.md`](/docs/contracts/acp-provider-registry.v1) | acp-provider-registry.v1 — unshipped operator declaration codec; registration never establishes readiness |
| [`adapter-degradation.v1.md`](/docs/contracts/adapter-degradation.v1) | adapter-degradation.v1 — what one client is told when its speech adapters fail |
| [`answer-card.v1.md`](/docs/contracts/answer-card.v1) | answer-card.v1 — what a frontend shows beside a spoken answer (the render frame is live; the four card types are a draft) |
| [`capture.v1.md`](/docs/contracts/capture.v1) | capture.v1 — a capture: annotated keyframes, marks, narration and OCR, from a frontend to the brain |
| [`avatar-action.v1.md`](/docs/contracts/avatar-action.v1) | avatar-action.v1 — the five avatar verbs, their closed arguments and the rig's vocabulary |
| [`avatar-puppet.v1.md`](/docs/contracts/avatar-puppet.v1) | avatar-puppet.v1 — what a rig draws from typed picks: overrides, gaze, clips, the director and the gate |
| [`frontend.v5.md`](/docs/contracts/frontend.v5) | frontend.v5 — the frontend WebSocket: the hello, owner admission, features as the minor, and every frame (`public`; schema) |
| [`admin.v6.md`](/docs/contracts/admin.v6) | admin.v6 — the Admin owner socket: one request, one answer, every request and projection (`owner`; schema) |
| [`decision.v1.md`](/docs/contracts/decision.v1) | decision.v1 — the typed-decision wire the gateway asks a local decision model over (live, off by default) |
| [`dictation.v1.md`](/docs/contracts/dictation.v1) | dictation.v1 — hold-to-talk, the typed words, and "scratch that" |
| [`links.v1.md`](/docs/contracts/links.v1) | links.v1 — an operator-activated list of web links (built; experimental) |
| [`meeting.v1.md`](/docs/contracts/meeting.v1) | meeting.v1 — typed meeting events into the gateway's store (gateway half built, off by default) |
| [`panel-card.v1.md`](/docs/contracts/panel-card.v1) | panel-card.v1 — the panel the brain or a tool fills, drawn in the conversation |
| [`connector.v1.md`](/docs/contracts/connector.v1) | connector.v1 — a connector: an account linked on the gateway's host, walked in the app |
| [`proactive-card.v1.md`](/docs/contracts/proactive-card.v1) | proactive-card.v1 — what Vulpine may say unprompted, and what the operator may answer |
| [`reading.v1.md`](/docs/contracts/reading.v1) | reading.v1 — the read verb on the wire: `start_read`, `reading_control`, `reading_progress` |
| [`reach-pair.v1.md`](/docs/contracts/reach-pair.v1) | reach-pair.v1 — pairing a new key with a gateway over reach: the invitation, one stream, one answer line |
| [`reach-ws.v1.md`](/docs/contracts/reach-ws.v1) | reach-ws.v1 — the frontend protocol's WebSocket carried over reach, one QUIC stream per WebSocket |
| [`reach-voice.v1.md`](/docs/contracts/reach-voice.v1) | reach-voice.v1 — one protocol 5 session over reach as a control stream and Opus datagrams (schema) |
| [`reach-mcp.v1.md`](/docs/contracts/reach-mcp.v1) | reach-mcp.v1 — one agent session over reach: a delegated key, a hello, then MCP JSON-RPC both ways (experimental; schema) |
| [`satellite-controls.v1.md`](/docs/contracts/satellite-controls.v1) | satellite-controls.v1 — a satellite's button, dial and mute switch on the wire |
| [`skill.v1.md`](/docs/contracts/skill.v1) | skill.v1 — a skill: a procedure in words over catalog tools |
| [`sidecar-envelope.v1.md`](/docs/contracts/sidecar-envelope.v1) | sidecar-envelope.v1 — the bounded tree a sidecar window draws: one snapshot, then revisioned patches (draft) |
| [`voice-profile-manifest.v1.md`](/docs/contracts/voice-profile-manifest.v1) | voice-profile-manifest.v1 — the consent and provenance a Voice Profile candidate must carry (draft) |
| [`turn-budget.v1.md`](/docs/contracts/turn-budget.v1) | turn-budget.v1 — each turn leg's millisecond budget; the numbers are in `turn-budget.v1.toml` |
| [`utterance.v1.md`](/docs/contracts/utterance.v1) | utterance.v1 — one typed record per committed spoken utterance |
| [`tool.v1.md`](/docs/contracts/tool.v1) | tool.v1 — a catalog tool: one call shape, eight shared actions, one manifest, any handler (accepted) |
| [`tool-index.v1.md`](/docs/contracts/tool-index.v1) | tool-index.v1 — the one list of registered tools, each with its provenance record (schema) |
| [`tool-pack.v1.md`](/docs/contracts/tool-pack.v1) | tool-pack.v1 — the unit a user downloads: one strict tar.gz, its pack.json, and the signed tools index (accepted) |
| [`extension-pack.v1.md`](/docs/contracts/extension-pack.v1) | extension-pack.v1 — one installable unit over the existing carriers: the manifest, its record and the one validator (accepted) |
| [`visual.v1.md`](/docs/contracts/visual.v1) | visual.v1 — a script visual: a sandboxed Luau program a frontend runs and draws |
| [`file.v1.md`](/docs/contracts/file.v1) | file.v1 — a file the gateway shows from its own disk: named on the render, fetched by its hash |
| [`page.v1.md`](/docs/contracts/page.v1) | page.v1 — a named web page from the gateway's registry, shown in the render panel |
| [`hardpoint.v1.md`](/docs/contracts/hardpoint.v1) | hardpoint.v1 — a typed runtime slot, the implementation a user binds into it, and the qualification before ready (accepted; 1.0 built for stt and tts) |
| [`hardpoint.stt.v1.md`](/docs/contracts/hardpoint.stt.v1) | hardpoint.stt.v1 — the `stt` slot: the built-ins, the STT worker wire on loopback, the probe and the fallback |
| [`hardpoint.tts.v1.md`](/docs/contracts/hardpoint.tts.v1) | hardpoint.tts.v1 — the `tts` slot: the built-in, a Wyoming TTS server on loopback, the probe (rendered to bytes, never played) and the fallback |
| `api-surfaces.toml` | the API catalog: every external surface, reach ALPN, protocol version constant and contract here, each with its stability label (public, owner, internal, experimental); rendered as [the API surfaces page](/docs/reference/api-surfaces). A new contract file needs a row (docs-check `api_catalog`) |
| [`hooks.v1.md`](/docs/contracts/hooks.v1) | hooks.v1 — a lifecycle boundary's typed event, from the subsystem that commits it to a consumer the user supplies (accepted; the session boundaries are live) |
| [`schema/`](/docs/contracts/json-schemas) | one JSON Schema per wire (frontend protocol 5, Admin 6, decision.v1), generated from `crates/protocol` and drift-tested; never hand-edited. Each has a contract file beside it that names every frame (docs-check `contract_frames`) |


## See also

- `docs/STANDARD.md`, "Templates" — the contract template.
- [ARCHITECTURE](/docs/the-voice-path/architecture) — one voice turn end to end.
- [Glossary](/docs/the-voice-path/glossary) — the names the contracts use.
