# Amy

- [Amy, Documentation](/docs): The complete reference for Amy, the personal health agent. Backend on Cloudflare, SDK in TypeScript, and recipes for shipping clients on top of it.
- [Architecture](/docs/architecture): The complete picture of how Amy's backend is built, why each piece was chosen, and where the seams are.
- [API Reference](/docs/api-reference): Every endpoint, every shape. The authoritative source is the live OpenAPI spec at /openapi.json on any deployed backend, this page mirrors it in human-readable form.
- Concepts
  - [Turns](/docs/concepts/turns): A turn is one round-trip of the agent: the user asks, Amy answers, and every quantitative claim in the answer has been checked. It's the unit of work the backend dispatches, persists, streams, and bi…
  - [Streaming](/docs/concepts/streaming): Amy streams every step of a turn, routing, agent thoughts, validator verdicts, the synthesised answer, over Server-Sent Events. One HTTP connection, one durable replay buffer, no websockets require…
  - [Memory](/docs/concepts/memory): What Amy remembers between turns, your goals, your preferences, the insights that earned validation. Memory is read into every turn's context, written to at the end of every turn, and fully visible…
  - [Webhooks](/docs/concepts/webhooks): Terra is Amy's single source of wearable and lab data. This page covers the inbound webhook contract: how Terra delivers events, how Amy verifies them, what happens after ingest, and how to replay th…
  - [Errors](/docs/concepts/errors): Every error Amy returns follows the same shape, has a stable code, and links here. This page is the catalog: every code, its HTTP status, when it fires, and how to recover.
- Guides
  - [Getting started](/docs/guides/getting-started): Ten minutes from zero to your first turn against a live Amy backend. Pick whichever path matches you.
  - [Local development](/docs/guides/local-development): The inner loop for working on Amy itself, the Worker, the CLI, the agents, the schemas. Edit a file, see the change in <2s. No deploys, no remote anything, everything on your laptop.
  - [Deploying to Cloudflare](/docs/guides/deploying): End-to-end deploy of the Amy backend to Cloudflare. ~30 minutes first time, ~2 minutes for subsequent updates. Everything here is idempotent, re-running a step is safe.
  - [Using the CLI](/docs/guides/using-the-cli): The amy CLI is the reference client for the Amy backend. Every command maps 1:1 to an SDK call. Every step waits for you to press enter before doing anything. Nothing happens by surprise.
- Recipes
  - [Recipe, Ask Amy a question](/docs/recipes/ask-a-question): Goal: the smallest possible turn against a live Amy backend. One question in, one answer out. Three variants depending on whether you want to block, stream, or fire-and-forget.
  - [Recipe, Stream events from a turn](/docs/recipes/stream-events): Goal: render a live UI from a turn's SSE event stream, spinners, agent names, validator verdicts, and the answer streaming in token by token. The "watch Amy think" feel from the CLI, in any client.
  - [Recipe, Connect a wearable](/docs/recipes/connect-a-wearable): Goal: let a user link their Whoop / Oura / Garmin / Fitbit / Apple Watch (or any of the 30+ providers Terra supports) to Amy. End state: a new row in GET /v1/sources and data flowing in via the Terra…
  - [Recipe, Upload a lab report](/docs/recipes/upload-a-lab-report): Goal: let a user upload a PDF (or phone photo) of their bloodwork, wait for it to be OCR'd and parsed into structured biomarkers, and surface "out of range" markers in your UI.
  - [Recipe, Build a mobile app with Claude Code](/docs/recipes/build-a-mobile-app): For non-developers. This recipe assumes you have no coding experience and are using Claude Code (the terminal AI agent) to drive the work. You don't need to understand any of the code Claude generate…
  - [Build a web app](/docs/recipes/build-a-web-app): A working web client for Amy. Next.js or Vite, the same API as the CLI, streaming SSE wired in so the user watches Amy think in real time.
  - [Recipe, Add a new wearable adapter](/docs/recipes/add-a-new-adapter): Goal: make Amy understand a wearable it doesn't already speak to. Two paths: either Terra already supports it (config-only) or it doesn't (a small custom adapter conforming to Amy's normalizer contra…
- SDKs
  - [SDK, TypeScript](/docs/sdk/typescript): The TypeScript SDK is the canonical client. It works in Bun, Node, Deno, browsers, and React Native. Every other language SDK is generated from the same OpenAPI spec.
- Internals
  - [Internals, Runtime](/docs/internals/runtime): How Amy's cloud actually executes on Cloudflare. One Worker (cloud/) ties together D1, R2, KV, Queues, and Cron. There are no Workflows yet, async work runs via a Queue consumer in the same Worker.…
  - [Internals, Agent Orchestration](/docs/internals/agent-orchestration): The deepest dive: what runTurn actually does. The full reference is src/orchestrator/index.ts, this page walks every step, every routing pattern, every validation gate, and the Fact Sheet contract t…
  - [Internals, Data Pipeline](/docs/internals/data-pipeline): How wearable + lab data gets from Terra into D1, what runs along the way, and how to recover when something falls over. The pipeline is small, webhook → raw_events insert → Queue → normalize → typed…
  - [Internals, Storage](/docs/internals/storage): Every column, every index, every key pattern. Amy uses three storage primitives, D1 (relational), R2 (blobs), KV (caches / ephemeral), plus an on-disk SQLite copy on the CLI machine. The definitive…