Docs overhaul

README.md

@@ -5,7 +5,9 @@
 
 # Reboot
 
-**Build AI Chat Apps — and full-stack web apps — with reactive, durable backends.**
+**Trust the code your agent writes.**
+
+A full-stack framework for the AI era.
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/reboot)](https://pypi.org/project/reboot/)
@@ -17,143 +19,191 @@
 
 ---
 
-Reboot is a framework for building **reactive, stateful, multiplayer AI chat
-apps** — visual apps that run inside ChatGPT, Claude, VS Code, Goose, and more.
-It also builds full-stack web apps with reactive backends and React frontends.
-
-With Reboot, you just write business logic — no wiring up databases, caches,
-queues, or retry loops. State survives failures by default. ACID transactions
-span multiple states. The React frontend stays in sync in real time. And your
-backend is automatically an MCP server.
+Modern app development is quickly becoming AI-assisted, or entirely
+vibe-coded. Can you trust these apps in production? Yes, but only if
+you build on a framework that handles the hard stuff and forces AI
+agents to ship clean, modular software.
 
-## AI Chat Apps
+Reboot solves the hard problems once, at the framework level, so
+neither you nor your coding agent has to. What Rust's borrow checker
+did for memory management, and React did for component-based
+frontends, Reboot does for your backend: **backend safety and data
+encapsulation**, enforced by the framework rather than by review.
 
-Build visual, interactive apps that run inside AI chat interfaces. Define a
-`Session` type as an entry point and your methods automatically become tools
-the AI can call:
-
-```python
-from reboot.api import (
-    API, Field, Methods, Model, Reader, Tool,
-    Transaction, Type, UI, Writer,
-)
+## Try Reboot with Claude Code or Codex
 
+Install the Reboot plugin:
 
-class CreateCounterResponse(Model):
-    counter_id: str = Field(tag=1)
+```sh
+curl -fsSL https://reboot.dev/install.sh | bash
+```
 
+Then describe what you want:
+
+> Build me a todo-list app I can use from a browser and from Claude and ChatGPT
+
+The agent proposes a design, scaffolds the project — API, backend,
+frontend, sign-in, tests — and runs it. See
+[Build with Claude Code](https://docs.reboot.dev/get_started/claude_code)
+or [Build with Codex](https://docs.reboot.dev/get_started/codex), or
+[build one by hand](https://docs.reboot.dev/get_started/python) to
+see every file.
+
+## Why a new framework?
+
+Agents are blazingly fast, junior engineers. You cannot trust them to
+build your application correctly without a rock-solid foundation to
+stand on. A harness isn't enough.
+
+- **Correct concurrency and retry safety.** Coding agents reliably
+  ship bugs in these two areas. The only way to fix this is to give
+  them constraints that make those bugs impossible by construction:
+  every method declares its kind — `reader`, `writer`,
+  `transaction`, or `workflow` — and Reboot enforces what each one may
+  do.
+- **Lose nothing on reboot.** Agents don't expect their code to
+  crash. Until now, the fix was to build on a durable execution
+  engine. Reboot goes further with **durable applications**: the
+  moment a function returns, its `state` is saved. Workflows resume
+  where they failed — the steps that already finished are memoized
+  rather than run again — and transactions keep everything atomic. No
+  database, no cache, no queue.
+- **Agents are lazy.** You asked for a frontend, but what you really
+  wanted was a reactive one. You wanted it to retry on an
+  intermittent network failure, but instead it threw an error and
+  never cleaned up its local React state. With Reboot you get these
+  features, and many more, without ever having to ask.
+- **Agents make code hard to review.** Even if some harness could get
+  an agent to handle all of the concerns above, would you want to
+  review that diff? Could you be sure it didn't introduce bugs?
+  Reboot's semantics are simple enough, for humans and agents alike,
+  that you can.
+
+## What it looks like
+
+Define your API with [Pydantic](https://docs.reboot.dev/define/pydantic)
+in Python (or [Zod](https://docs.reboot.dev/define/zod) in
+TypeScript). Every method declares its kind, and whether an AI may
+call it:
 
-class UserState(Model):
-    pass
+```python
+from reboot.api import API, Field, Methods, Model, Reader, Tool, Type, Writer
 
 
-class CounterState(Model):
-    value: int = Field(tag=1, default=0)
+class AccountState(Model):
+    balance: int = Field(tag=1, default=0)
 
 
-class GetResponse(Model):
-    value: int = Field(tag=1)
+class DepositRequest(Model):
+    amount: int = Field(tag=1)
 
 
-class IncrementRequest(Model):
-    """Request with an amount parameter."""
-    amount: int | None = Field(tag=1, default=None)
+class BalanceResponse(Model):
+    balance: int = Field(tag=1)
 
 
 api = API(
-    User=Type(
-        state=UserState,
-        methods=Methods(
-            create_counter=Transaction(
-                request=None,
-                response=CreateCounterResponse,
-                description="Create a new Counter.",
-                mcp=Tool(),
-            ),
-        ),
-    ),
-    Counter=Type(
-        state=CounterState,
+    Account=Type(
+        state=AccountState,
         methods=Methods(
-            show_clicker=UI(
-                request=None,
-                path="frontend/mcp/clicker",
-                title="Counter Clicker",
-                description="Interactive clicker UI.",
-            ),
-            create=Writer(
-                request=None,
+            deposit=Writer(
+                request=DepositRequest,
                 response=None,
-                factory=True,
-                description="Create the counter at zero.",
-                mcp=None,
-            ),
-            get=Reader(
-                request=None,
-                response=GetResponse,
-                description="Get the current counter "
-                "value.",
+                description="Add funds to the account.",
                 mcp=Tool(),
             ),
-            increment=Writer(
-                request=IncrementRequest,
-                response=None,
-                description="Increment the counter.",
+            balance=Reader(
+                request=None,
+                response=BalanceResponse,
+                description="The account's current balance.",
                 mcp=Tool(),
             ),
         ),
     ),
 )
 ```
 
-### Dive in!
-
-- [What is an AI Chat App?](https://docs.reboot.dev/ai_chat_apps/what_is)
-- [Get Started (Python)](https://docs.reboot.dev/ai_chat_apps/get_started)
-- [AI Chat App Examples](https://docs.reboot.dev/ai_chat_apps/examples)
-
-## Full-stack apps
-
-Build reactive backends with React frontends — great as a full-page extension
-of your AI chat app, or as a standalone web app.
-
-- [Python Quickstart](https://docs.reboot.dev/full_stack_apps/python)
-- [TypeScript Quickstart](https://docs.reboot.dev/full_stack_apps/typescript)
-- [Full-stack Examples](https://docs.reboot.dev/full_stack_apps/examples)
+Implement it. `self.state` is durable: when the method returns, the
+new state is saved, all of it or none of it.
 
-TypeScript backend support is in alpha: the core of Reboot works in
-both languages, but some features — including MCP apps, `UI` methods,
-the built-in OAuth sign-in flow, and durable agents — are currently
-Python-only. If you don't have a strong preference, start with Python.
-
-## Key features
-
-**Automatic MCP server.** `Session` methods are automatically exposed as
-MCP tools. Other types can opt in with `mcp=Tool()`. `UI` methods open
-React apps in the AI's chat. No glue code.
-
-**Durable state by default.** States survive process crashes, deployments, and
-chaos. No external database required.
-
-**ACID transactions across states.** `transaction` methods compose atomically
-across many state instances running on different machines.
-
-**Reactive React frontend.** Generated hooks keep your UI in sync
-without manual management of WebSockets, caches, or polling.
+```python
+class AccountServicer(Account.Servicer):
+
+    async def deposit(
+        self,
+        context: WriterContext,
+        request: Account.DepositRequest,
+    ) -> None:
+        self.state.balance += request.amount
+
+    async def balance(
+        self,
+        context: ReaderContext,
+    ) -> Account.BalanceResponse:
+        return Account.BalanceResponse(balance=self.state.balance)
+```
 
-**Method system.** Code is safer to write (and _read_) with a clear API
-and methods with enforced constraints: `reader` (concurrent, read-only),
-`writer` (serialized, mutating), `transaction` (ACID, cross-state),
-`workflow` (long-running, durable, cancellable), `ui` (React app in AI
-chat). The runtime enforces these guarantees.
+Call it from React through generated, typed hooks. `useBalance`
+re-renders whenever the balance changes, whether this user, another
+user, a workflow, or an AI changed it:
 
-**API-first, code-generated.** Define APIs using Pydantic (Python) or
-Zod (TypeScript). Reboot generates type-safe client, server, and React
-stubs.
+```tsx
+const account = useAccount({ id });
+const { response } = account.useBalance();
 
-## Documentation
+await account.deposit({ amount: 50 });
+```
 
-Full documentation at [docs.reboot.dev](https://docs.reboot.dev/).
+The same two methods are tools for Claude, ChatGPT, or any other MCP
+client, because they were declared with `mcp=Tool()`.
+
+## One backend, many frontends
+
+One app to serve every user — human or machine. You and your agents
+can build any kind of app with Reboot:
+
+- **Humans** reach it through a
+  [web app](https://docs.reboot.dev/surfaces/web), a
+  [React Native app](https://docs.reboot.dev/surfaces/react_native)
+  (alpha), or an
+  [AI chat app](https://docs.reboot.dev/surfaces/ai_chat) inside
+  ChatGPT, Claude, or VS Code, where `UI` methods render React
+  components in the conversation.
+- **Agents** reach it over MCP: every method marked `mcp=Tool()` is a
+  tool. An agent can also run
+  [inside your app](https://docs.reboot.dev/agents), with durable,
+  replay-safe model and tool calls.
+- **Services** reach it from your own backend code, a script, or a
+  plain HTTP request.
+
+Signed-in users come built in. Plug in your favorite auth provider —
+Google, GitHub, Auth0, Ory — and Reboot runs the OAuth server in front
+of it, so a person signing in auto-constructs their `User`: the
+per-user entry point the rest of your app hangs off, and the same
+`User` on every surface. See
+[Users and sign-in](https://docs.reboot.dev/users/overview).
+
+## Status
+
+Python backends are supported today. TypeScript backends and React
+Native frontends are in alpha: the core of Reboot works in both
+languages, but AI chat apps, `UI` methods, the built-in OAuth sign-in
+flow, and durable agents are Python-only for now. More languages are
+coming.
+
+## Get started today
+
+Reboot is open source. Run a Reboot app on your own infrastructure or
+on Reboot Cloud.
+
+- [Reboot Cloud](https://cloud.reboot.dev/) — deploy with
+  `rbt cloud up`.
+- [Deploy on your own](https://docs.reboot.dev/deploy_on_your_own) —
+  `rbt serve` on your own machines or Kubernetes.
+- [Documentation](https://docs.reboot.dev/) — start with
+  [How Reboot works](https://docs.reboot.dev/concepts).
+- [Examples](https://docs.reboot.dev/get_started/examples) — complete
+  applications to run and take apart.
 
 ## Community
 

documentation/docs/learn_more/agents.mdx → documentation/docs/agents.mdx

@@ -1,11 +1,17 @@
-# Agents
+# Agents inside your app
+
+An AI agent can reach your application from outside, over
+[MCP](/surfaces/ai_chat). It can also run *inside* it, as part of your
+own business logic — that is what this page is about.
 
 Reboot's `reboot.agents` package lets you run [Pydantic AI](https://ai.pydantic.dev/)
-agents inside Reboot [workflows](/learn_more/implement/workflows) with
+agents inside Reboot [workflows](/implement/workflows) with
 **durable, replay-safe execution
 of model calls and tool calls** -- you get back the same answer on
 re-runs without re-hitting the LLM provider, and tool side-effects
-that have already completed are not repeated.
+that have already completed are not repeated. A model call is the most
+expensive, least deterministic thing your app does; running it in a
+workflow means a crash never pays for it twice.
 
 This page covers what's specific to running a Pydantic AI agent on
 Reboot. For everything that isn't Reboot-specific (model providers,
@@ -22,7 +28,7 @@ When you wrap a Pydantic AI agent with Reboot's `Agent`:
 - **Every tool call** -- whether registered via `@agent.tool`, passed
   as `tools=`, or contributed via `toolsets=` -- is memoized too,
   so a tool's side effects aren't repeated on replay. During [effect
-  validation](/learn_more/side_effects) tools DO re-run, which helps
+  validation](/side_effects) tools DO re-run, which helps
   surface non-determinism early.
 - **Streaming runs are drained inside a memoized block.** Even on
   the first run, events arrive in a single batch once the model call
@@ -235,7 +241,7 @@ Reboot wraps every tool call in `at_least_once`. On replay, the stored
 return value is reused without invoking your tool function. You
 therefore can't rely on your tool function being invoked again on
 replay. Note that during [effect
-validation](/learn_more/side_effects), Reboot re-runs your tool to
+validation](/side_effects), Reboot re-runs your tool to
 verify your code is deterministic, so if you are performing external
 side-effects inside your tool body you need to ensure they are done
 idempotently (or consider using an `at_most_once` block instead, but