diff --git a/README.md b/README.md
index fca5c820c..ed190f406 100644
--- a/README.md
+++ b/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,88 +19,103 @@
 
 ---
 
-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(),
             ),
         ),
@@ -106,54 +123,87 @@ api = API(
 )
 ```
 
-### 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
 
diff --git a/documentation/docs/learn_more/agents.mdx b/documentation/docs/agents.mdx
similarity index 97%
rename from documentation/docs/learn_more/agents.mdx
rename to documentation/docs/agents.mdx
index 09a0339bd..f9b8be330 100644
--- a/documentation/docs/learn_more/agents.mdx
+++ b/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
diff --git a/documentation/docs/ai_chat_apps/examples.mdx b/documentation/docs/ai_chat_apps/examples.mdx
deleted file mode 100644
index c24bdad2f..000000000
--- a/documentation/docs/ai_chat_apps/examples.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
-# AI Chat App Examples
-
-## `agent-wiki`
-
-[`reboot-dev/reboot-agent-wiki`](https://github.com/reboot-dev/reboot-agent-wiki) - _Python backend, React AI Chat App UIs_
-
-The `agent-wiki` example is a shared knowledge base humans
-and AIs can both read from and write to. Users hand in raw
-conversation transcripts; a background "librarian" agent
-(built with Pydantic AI) progressively distills those
-transcripts into a small, well-organized set of markdown
-pages linked from the wiki's own markdown body, which
-serves as a living table of contents. Humans browse the
-result in embedded React UIs.
-
-It demonstrates:
-
-* `UI` methods that render React views (wiki, page,
-  transcript) inside the AI chat interface.
-* A long-running [`workflow`](/learn_more/implement/workflows)
-  method (`Wiki.ingest`) that
-  acts as a per-wiki background agent, reacting to new
-  transcripts as they arrive.
-* `Transaction`s that atomically create related state
-  across multiple types (e.g. `User.create_wiki` creates a
-  `Wiki` and records its ID on the user in one step).
-* Cross-state references via `<StateType>:<state_id>` URIs
-  embedded in markdown, letting the agent build a graph of
-  pages without a dedicated link table.
-* An in-process test suite that exercises the librarian
-  workflow with a scripted Pydantic AI `FunctionModel`, so
-  no real Anthropic calls are needed in CI.
-
-## `chick-potle`
-
-[`reboot-dev/reboot-chick-potle`](https://github.com/reboot-dev/reboot-chick-potle) - _Python backend, React AI Chat App UIs_
-
-The `chick-potle` example is a small food-ordering AI Chat
-App. The AI calls tools to start an order, browse the menu,
-and add or remove items from the cart; humans see two
-embedded React UIs — a menu grid and a cart — rendered
-alongside the conversation.
-
-It demonstrates:
-
-* `UI` methods that render React views (menu, cart) inside
-  the AI chat interface.
-* The `User` type: auto-constructed per authenticated user,
-  acting as an entry point that creates a `FoodOrder` via a
-  `Transaction` (`User.start_order`).
-* MCP `Tool`s (`get_menu`, `get_cart`, `add_to_cart`,
-  `remove_from_cart`) that let the AI drive the order
-  programmatically.
-* Generated React hooks (`useFoodOrder()`) shared between
-  the menu and cart UIs, so adding an item from one view
-  immediately updates the other.
-
-## `ai-chat-counter`
-
-_Python backend, React AI Chat App UIs_
-
-The `ai-chat-counter` example demonstrates building an AI Chat App —
-a counter with visual UIs that run inside ChatGPT, Claude, VS
-Code, Goose, or any compatible AI client.
-
-It demonstrates:
-
-* `UI` methods that open React UIs in the AI chat interface.
-* The `User` type: auto-constructed per authenticated user,
-  acting as an entry point that creates other state types.
-* Generated React hooks (`useCounter()`) that work in both AI
-  and browser contexts.
-* An `App.tsx` React component that implements the UI.
-
-Follow the [AI Chat App quickstart](/ai_chat_apps/get_started)
-to build this example from scratch.
diff --git a/documentation/docs/ai_chat_apps/get_started.mdx b/documentation/docs/ai_chat_apps/get_started.mdx
deleted file mode 100644
index d9d90545f..000000000
--- a/documentation/docs/ai_chat_apps/get_started.mdx
+++ /dev/null
@@ -1,1468 +0,0 @@
-import { CodeStepByStep, Step } from "../../src/components/Steps";
-
-# Get Started (hand-written)
-
-Build a visual, reactive app that runs inside ChatGPT, Claude, VS Code,
-Goose, or any compatible AI client.
-
-If you want to use **Claude Code** to build your AI Chat App, see the [getting
-started with Claude Code](get_started_claude_code) guide. If you want to use **Codex**
-to build your app, see the [getting started with Codex](get_started_codex) guide.
-If, however, you want to
-see exactly what we're feeding these AIs, then this step-by-step guide
-is for you!
-
-<CodeStepByStep>
-<Step
-  title="Setup your project"
-  description={`
-
-Create a folder for your project and install dependencies.
-
-:::info
-Reboot requires Python >= 3.10 and < 3.13, Docker, and
-Node.js >= 20.10.
-:::
-
-`}>
-
-```sh
-mkdir ai-chat-counter && cd ai-chat-counter
-uv init --python 3.12.11
-uv add reboot pydantic
-```
-
-</Step>
-<Step
-  title="Make sure Docker is running"
->
-
-```sh
-docker ps
-```
-
-</Step>
-<Step
-  title="Define your API"
-  description={`
-
-Reboot applications define their API with Pydantic. A Reboot API is
-centered on _types_, which contain _state_ and _methods_. Start by
-creating a Python file for your API definition.
-
-`}>
-
-```sh
-mkdir -p api/ai_chat_counter/v1 && touch api/ai_chat_counter/v1/counter.py
-```
-
-</Step>
-<Step
-  title="Define your state and methods"
-  description={`
-
-Define a \`User\` type and a \`Counter\` type.
-
-Naming a type \`User\` in your \`API(...)\` is special:
-
-- A \`User\` instance is automatically created for each authenticated
-  user that connects to your app.
-- During development you "sign in" by picking one of the built-in
-  \`Development\` OAuth provider's fake identities, so every user of
-  your app gets a \`User\` instance.
-- \`User\` acts as an entry point: its methods create other state
-  types (like \`Counter\`) whose IDs the AI tracks in its context
-  window.
-- Use \`mcp=Tool()\` on every method you want the AI to call,
-  including \`User\` methods. Use \`mcp=None\` to hide a method.
-
-`}>
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
-
-```python
-# api/ai_chat_counter/v1/counter.py
-from reboot.api import (
-    API,
-    UI,
-    Field,
-    Methods,
-    Model,
-    Reader,
-    Tool,
-    Transaction,
-    Type,
-    Writer,
-)
-
-
-class CreateCounterRequest(Model):
-    description: str = Field(tag=1)
-
-
-class CreateCounterResponse(Model):
-    counter_id: str = Field(tag=1)
-
-
-class CounterEntry(Model):
-    counter_id: str = Field(tag=1)
-    description: str = Field(tag=2)
-
-
-class ListCountersResponse(Model):
-    counters: list[CounterEntry] = Field(tag=1, default_factory=list)
-
-
-class UserState(Model):
-    counter_ids: list[str] = Field(tag=1, default_factory=list)
-
-
-class InitializeCounterRequest(Model):
-    description: str = Field(tag=1)
-    # The `user_id` of the Counter's owner, recorded so that only the
-    # owner may call the Counter later.
-    owner_id: str = Field(tag=2)
-
-
-class DescriptionResponse(Model):
-    description: str = Field(tag=1)
-
-
-class CounterState(Model):
-    value: int = Field(tag=1, default=0)
-    description: str = Field(tag=2, default="")
-    owner_id: str = Field(tag=3, default="")
-
-
-class GetResponse(Model):
-    value: int = Field(tag=1)
-
-
-class IncrementRequest(Model):
-    """Request with an amount parameter."""
-    amount: int | None = Field(tag=1, default=None)
-
-
-api = API(
-    User=Type(
-        state=UserState,
-        methods=Methods(
-            create_counter=Transaction(
-                request=CreateCounterRequest,
-                response=CreateCounterResponse,
-                description="Create a new Counter with a "
-                "description of what it counts. Returns "
-                "the `counter_id`, which is not "
-                "human-readable but should be passed to "
-                "future tool calls that need it.",
-                mcp=Tool(),
-            ),
-            list_counters=Reader(
-                request=None,
-                response=ListCountersResponse,
-                description="List all counters created "
-                "by this user. Returns `counter_id` and "
-                "description for each. The `counter_id` "
-                "is not human-readable, but use it when "
-                "calling tools that take a `counter_id`.",
-                mcp=Tool(),
-            ),
-        ),
-    ),
-    Counter=Type(
-        state=CounterState,
-        methods=Methods(
-            show_clicker=UI(
-                request=None,
-                path="frontend/mcp/clicker",
-                title="Counter Clicker",
-                description="Interactive clicker UI "
-                "for the counter.",
-            ),
-            create=Writer(
-                request=InitializeCounterRequest,
-                response=None,
-                factory=True,
-                description="Create the counter at its initial value.",
-                mcp=None,
-            ),
-            get=Reader(
-                request=None,
-                response=GetResponse,
-                description="Get the current counter "
-                "value.",
-                mcp=Tool(),
-            ),
-            increment=Writer(
-                request=IncrementRequest,
-                response=None,
-                description="Increment the counter by "
-                "the specified amount.",
-                mcp=Tool(),
-            ),
-            description=Reader(
-                request=None,
-                response=DescriptionResponse,
-                mcp=None,
-            ),
-        ),
-    ),
-)
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-:::info Naming conventions
-Your state class should end in `State`, e.g., `UserState`,
-`CounterState`. All fields on `User` state must have default
-values, because `User` instances are auto-constructed for
-each authenticated user.
-:::
-
-</Step>
-<Step
-  title="Create your servicer"
-  description={`
-
-For each non-\`UI\` method, you implement a servicer method in Python.
-
-\`UI\` methods have no backend code — they are implemented by a React
-component written in TypeScript.
-
-`}>
-
-```sh
-mkdir -p backend/src/servicers && touch backend/src/servicers/counter.py
-```
-
-</Step>
-<Step
-  title="Implement your servicer"
-  description={`
-
-You implement one servicer class per type. \`UserServicer\`
-handles the \`create_counter\` transaction; \`CounterServicer\`
-handles the counter operations. Each method gets a \`context\`
-and optionally a \`request\`. You access state via
-\`self.state\`.
-
-`}>
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/backend/src/servicers/counter.py&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/backend/src/servicers/counter.py -->
-
-```python
-# backend/src/servicers/counter.py
-from ai_chat_counter.v1.counter import (
-    CounterEntry,
-    CreateCounterRequest,
-    CreateCounterResponse,
-    InitializeCounterRequest,
-    ListCountersResponse,
-)
-from ai_chat_counter.v1.counter_rbt import Counter, User
-from rbt.v1alpha1.errors_pb2 import Ok, PermissionDenied, Unauthenticated
-from reboot.aio.auth.authorizers import Authorizer, allow_if, is_app_internal
-from reboot.aio.contexts import (
-    ReaderContext,
-    TransactionContext,
-    WriterContext,
-)
-from typing import Optional
-
-
-def _caller_is_owner(
-    *,
-    context: ReaderContext,
-    state: Optional[Counter.State],
-    **kwargs,
-):
-    """Allow when the caller's `user_id` matches the Counter's recorded
-    `owner_id`. A not-yet-constructed Counter (`state is None`) falls
-    through to deny."""
-    if context.auth is None or not context.auth.user_id:
-        return Unauthenticated()
-    if state is not None and context.auth.user_id == state.owner_id:
-        return Ok()
-    return PermissionDenied()
-
-
-class UserServicer(User.Servicer):
-    """Servicer for the User state machine."""
-
-    async def create_counter(
-        self,
-        context: TransactionContext,
-        request: CreateCounterRequest,
-    ) -> CreateCounterResponse:
-        """Create a new Counter and return its ID."""
-        counter, _ = await Counter.create(
-            context,
-            description=request.description,
-            owner_id=context.state_id,
-        )
-        self.state.counter_ids.append(counter.state_id)
-        return CreateCounterResponse(
-            counter_id=counter.state_id,
-        )
-
-    async def list_counters(
-        self,
-        context: ReaderContext,
-    ) -> ListCountersResponse:
-        """List all counters created by this user."""
-        counters = []
-        for counter_id in self.state.counter_ids:
-            response = await Counter.ref(counter_id).description(context)
-            counters.append(
-                CounterEntry(
-                    counter_id=counter_id,
-                    description=response.description,
-                )
-            )
-        return ListCountersResponse(counters=counters)
-
-
-class CounterServicer(Counter.Servicer):
-    """Servicer for the Counter state machine."""
-
-    def authorizer(self) -> Authorizer:
-        return Counter.Authorizer(
-            # `create` is restricted to trusted app code and records
-            # the counter's owner; every other method is restricted to
-            # that owner (or, again, to trusted app code).
-            create=allow_if(all=[is_app_internal]),
-            get=allow_if(any=[_caller_is_owner, is_app_internal]),
-            increment=allow_if(any=[_caller_is_owner, is_app_internal]),
-            description=allow_if(any=[_caller_is_owner, is_app_internal]),
-        )
-
-    async def create(
-        self,
-        context: WriterContext,
-        request: InitializeCounterRequest,
-    ) -> None:
-        """Initialize the counter with a description and record its
-        owner."""
-        self.state.description = request.description
-        self.state.owner_id = request.owner_id
-
-    async def description(
-        self,
-        context: ReaderContext,
-    ) -> Counter.DescriptionResponse:
-        """Get the counter's description."""
-        return Counter.DescriptionResponse(
-            description=self.state.description,
-        )
-
-    async def increment(
-        self,
-        context: WriterContext,
-        request: Counter.IncrementRequest,
-    ) -> None:
-        """Increment the counter by the specified amount."""
-        self.state.value += (
-            request.amount if request.amount is not None else 1
-        )
-
-    async def get(
-        self,
-        context: ReaderContext,
-    ) -> Counter.GetResponse:
-        """Get the current counter value."""
-        return Counter.GetResponse(value=self.state.value)
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Create your entrypoint"
-  description={`
-
-Create a \`backend/src/main.py\` file. In it, you define the backend
-servicers this application serves.
-
-`}>
-
-```sh
-touch backend/src/main.py
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/backend/src/main.py&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/backend/src/main.py -->
-
-```python
-# backend/src/main.py
-import asyncio
-from reboot.aio.applications import Application
-from reboot.aio.auth.oauth import OAuth
-from reboot.aio.auth.oauth_providers import (
-    Development,
-    OAuthProviderByEnvironment,
-)
-from servicers.counter import CounterServicer, UserServicer
-
-
-async def main() -> None:
-    application = Application(
-        title="Chat Counter",
-        description=(
-            "Lets a chat client create, list, increment, and "
-            "show counters on your behalf."
-        ),
-        servicers=[UserServicer, CounterServicer],
-        oauth=OAuth(
-            provider=OAuthProviderByEnvironment(
-                dev=Development(),
-                # TODO: set a real provider (e.g. `Google(...)`) before
-                # production; `prod=None` makes a production deployment fail
-                # to start until one is chosen.
-                prod=None,
-            )
-        ),
-    )
-    await application.run()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Set up your React UI"
-  description={`
-
-Create a React app for your \`show_clicker\` UI method. Each
-\`UI\` method points to a directory containing an
-\`index.html\`, which is what will be shown in the AI's chat.
-
-`}>
-
-```sh
-mkdir -p frontend/mcp/clicker
-cd frontend && npm init -y
-npm install react react-dom @reboot-dev/reboot-react @reboot-dev/reboot-api
-npm install -D @vitejs/plugin-react vite vite-plugin-singlefile typescript @types/react @types/react-dom
-cd ..
-```
-
-</Step>
-<Step
-  title="Style the clicker UI"
-  description={`
-
-Create a CSS module for the clicker component. This keeps the
-styling separate from the component logic.
-
-`}>
-
-```sh
-touch frontend/mcp/clicker/App.module.css
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.module.css&syntax=css) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.module.css -->
-
-```css
-/* frontend/mcp/clicker/App.module.css */
-
-/*
- * The clicker renders inline inside the MCP host (e.g. Claude.ai),
- * so it inherits the host's color scheme. We set every color
- * explicitly — never relying on inherited text color — and provide
- * a dark variant via `prefers-color-scheme` so the widget stays
- * legible in both Claude.ai's light and dark modes.
- */
-.container {
-  display: flex;
-  align-items: center;
-  width: fit-content;
-  margin: 0 auto;
-  gap: 12px;
-  font-family: system-ui, sans-serif;
-  padding: 16px 24px;
-  border: 1px solid #e0e0e0;
-  border-radius: 12px;
-  background: #fafafa;
-  color: #1a1a1a;
-}
-
-.value {
-  font-size: 32px;
-  font-weight: 600;
-  min-width: 48px;
-  text-align: center;
-  color: inherit;
-}
-
-.button {
-  font-size: 20px;
-  font-weight: 600;
-  width: 40px;
-  height: 40px;
-  border-radius: 8px;
-  border: 1px solid #ccc;
-  background: #f5f5f5;
-  color: #1a1a1a;
-  cursor: pointer;
-}
-
-.button:hover:not(:disabled) {
-  background: #ebebeb;
-}
-
-.button:disabled {
-  cursor: default;
-  opacity: 0.5;
-}
-
-.popOut {
-  font-size: 13px;
-  padding: 6px 10px;
-  border: none;
-  border-radius: 8px;
-  background: transparent;
-  color: inherit;
-  opacity: 0.7;
-  cursor: pointer;
-  text-decoration: underline;
-}
-
-.popOut:hover {
-  opacity: 1;
-}
-
-@media (prefers-color-scheme: dark) {
-  .container {
-    border-color: #3a3a3a;
-    background: #1e1e1e;
-    color: #f0f0f0;
-  }
-
-  .button {
-    border-color: #4a4a4a;
-    background: #2d2d2d;
-    color: #f0f0f0;
-  }
-
-  .button:hover:not(:disabled) {
-    background: #3a3a3a;
-  }
-}
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Build the clicker UI"
-  description={`
-
-The React component uses the generated \`useCounter()\` hook.
-The Counter ID is automatically provided by the framework when
-the UI is opened.
-
-- \`counter.useGet()\` watches the result of the \`get\` \`Reader\`
-  method; the response reactively updates whenever the backend
-  state changes.
-- \`counter.increment()\` calls the corresponding \`Writer\` method.
-
-`}>
-
-```sh
-touch frontend/mcp/clicker/App.tsx
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.tsx&syntax=tsx) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.tsx -->
-
-```tsx
-// frontend/mcp/clicker/App.tsx
-import {
-  type UseCounterApi,
-  useCounter,
-} from "@api/ai_chat_counter/v1/counter_rbt_react";
-import { useMcpApp } from "@reboot-dev/reboot-react";
-import { useState, type FC } from "react";
-import css from "./App.module.css";
-
-export const ClickerApp: FC = () => {
-  const { counter, isLoading } = useCounter();
-
-  if (isLoading) {
-    return <div>loading...</div>;
-  }
-
-  // `isLoading` is checked first: while it is true, `counter` is
-  // still `undefined`. Reaching this check with `undefined` therefore
-  // means resolution finished and there is genuinely no default
-  // Counter id.
-  if (counter === undefined) {
-    console.error("No default Counter id was available; cannot render.");
-    return <div>An error occurred, sorry about that!</div>;
-  }
-
-  return <Clicker counter={counter} />;
-};
-
-const Clicker: FC<{ counter: UseCounterApi }> = ({ counter }) => {
-  const [isPending, setIsPending] = useState(false);
-  const { response, isLoading } = counter.useGet();
-
-  // Reuse the MCP-inferred id to deep-link into the standalone web
-  // SPA for the very same counter.
-  const counterId = counter.state_id;
-
-  // The MCP host's app handle, used to open the deep link (see
-  // `handlePopOut`). `null` when not running under an MCP host.
-  const mcpApp = useMcpApp();
-
-  const value = response?.value ?? 0;
-
-  const handleIncrement = async () => {
-    setIsPending(true);
-    try {
-      await counter.increment({ amount: 1 });
-    } finally {
-      setIsPending(false);
-    }
-  };
-
-  const handlePopOut = async () => {
-    // The standalone web app lives on its own origin (in production
-    // typically a CDN), never on the backend's, so `VITE_WEB_APP_URL`
-    // is required in every environment: `web/.env.development` points
-    // it at the local Vite dev server, and `web/.env.production` must
-    // name the real web-app host.
-    const webAppUrl = import.meta.env.VITE_WEB_APP_URL;
-    const url =
-      webAppUrl + "/__/frontend/web/?counter=" + encodeURIComponent(counterId);
-    // The sandboxed MCP UI iframe blocks `window.open` unless the
-    // host grants `allow-popups`, so ask the host to open the link
-    // via the MCP Apps `ui/open-link` request. Fall back to
-    // `window.open` when not under an MCP host (or it declines).
-    if (mcpApp?.openLink) {
-      try {
-        const { isError } = await mcpApp.openLink({ url });
-        if (!isError) {
-          return;
-        }
-      } catch {
-        // Fall through to `window.open` below.
-      }
-    }
-    window.open(url, "_blank", "noopener");
-  };
-
-  if (isLoading && response === undefined) {
-    return <div>loading...</div>;
-  }
-
-  return (
-    <div className={css.container}>
-      <span className={css.value}>{value}</span>
-      <button
-        onClick={handleIncrement}
-        disabled={isPending}
-        className={css.button}
-      >
-        +
-      </button>
-      <button
-        onClick={handlePopOut}
-        className={css.popOut}
-        title="Open this counter in the web app"
-      >
-        Open in web app ↗
-      </button>
-    </div>
-  );
-};
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Create the entry point for the UI"
-  description={`
-
-Wrap your component in a \`RebootClientProvider\`. When building an AI
-chat app, no \`url\` prop is needed here — the provider automatically
-detects the environment.
-
-`}>
-
-```sh
-touch frontend/mcp/clicker/main.tsx frontend/mcp/clicker/index.html
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/main.tsx&syntax=tsx) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/main.tsx -->
-
-```tsx
-// frontend/mcp/clicker/main.tsx
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import { RebootClientProvider } from "@reboot-dev/reboot-react";
-import { ClickerApp } from "./App";
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <RebootClientProvider>
-      <ClickerApp />
-    </RebootClientProvider>
-  </StrictMode>
-);
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/index.html&syntax=html) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/index.html -->
-
-```html
-<!-- frontend/mcp/clicker/index.html -->
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Counter Clicker</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Configure Vite"
-  description={`
-
-A single \`vite.config.ts\` drives three jobs. The dev server is
-\`vite\`; the two builds are selected by the \`RBT_BUILD_TARGET\` env
-var (set per UI by \`build.mjs\`):
-
-- \`vite\` (dev server) serves Hot Module Replacement for every
-  \`mcp/<name>\` UI _and_ the standalone \`web/\` SPA you'll add below.
-- \`RBT_BUILD_TARGET=mcp:<name> vite build\` bundles one \`UI\` method's
-  React app into a single, self-contained
-  \`dist/mcp/<name>/index.html\` using
-  [\`vite-plugin-singlefile\`](https://www.npmjs.com/package/vite-plugin-singlefile).
-  The Reboot server serves it at \`/__/frontend/mcp/<name>/index.html\`.
-- \`RBT_BUILD_TARGET=web vite build\` bundles the \`web/\` SPA into
-  \`dist/web/\`, served at \`/__/frontend/web/\`.
-
-The config auto-discovers MCP UIs from the \`mcp/\` directory, so
-adding a new \`mcp/<name>/index.html\` is all it takes to build it.
-
-`}>
-
-<!-- TODO(rjh): replace this whole section with an `npm create` that scaffolds this stuff -->
-
-```sh
-touch frontend/vite.config.ts
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/vite.config.ts&syntax=ts) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/vite.config.ts -->
-
-```ts
-// Vite configuration for Reboot UIs.
-//
-// One config drives three jobs. The dev server is selected by
-// `command === "serve"`; the two build shapes are selected by the
-// `RBT_BUILD_TARGET` env var, set per UI by `build.mjs`. `mode` keeps
-// its conventional Vite values — `development` (serve) / `production`
-// (build) — so the matching `.env.<mode>` files load as usual:
-//
-//   * `vite` (serve): a single dev server that delivers HMR for every
-//     `mcp/<name>` UI AND the standalone `web/` SPA, all under
-//     `base: "/__/frontend/"`. Envoy proxies that prefix to this dev
-//     server (`run --config=hmr`).
-//   * `RBT_BUILD_TARGET=mcp:<name> vite build`: builds one MCP UI into
-//     a single, self-contained `dist/mcp/<name>/index.html` (assets
-//     inlined via `vite-plugin-singlefile`). The framework serves it
-//     at `/__/frontend/mcp/<name>/index.html` in dist mode.
-//   * `RBT_BUILD_TARGET=web vite build`: builds the `web/` SPA into
-//     `dist/web/` with normal (non-inlined) assets. Its `base` is
-//     `/__/frontend/web/` so asset URLs resolve when served at that
-//     prefix. In Vite's `production` mode, it reads
-//     `web/.env.production`.
-import fs from "fs";
-import path from "path";
-import react from "@vitejs/plugin-react";
-import { defineConfig, type Plugin } from "vite";
-import { viteSingleFile } from "vite-plugin-singlefile";
-
-// A served directory under `/__/frontend/` requested without its
-// trailing slash (e.g. `/__/frontend/web`) doesn't match Vite's static
-// index.html serving, which expects `/__/frontend/web/`, so it 404s.
-// Redirect the slash-less form to the canonical trailing-slash form so
-// the `web/` SPA and each `mcp/<name>` UI load with or without the
-// trailing slash — matching how the framework's dist-mode server
-// behaves. Only a path that resolves to a real directory with an
-// `index.html` is redirected, so Vite's own internal module URLs
-// (`@vite/client`, `@react-refresh`) and source or asset files fall
-// through untouched.
-function redirectFrontendDirTrailingSlash(root: string): Plugin {
-  const prefix = "/__/frontend/";
-  return {
-    name: "reboot-frontend-dir-trailing-slash",
-    configureServer(server) {
-      server.middlewares.use((req, res, next) => {
-        const url = req.url ?? "";
-        const queryAt = url.indexOf("?");
-        const pathname = queryAt === -1 ? url : url.slice(0, queryAt);
-        if (pathname.startsWith(prefix) && !pathname.endsWith("/")) {
-          const subpath = pathname.slice(prefix.length);
-          if (fs.existsSync(path.join(root, subpath, "index.html"))) {
-            const query = queryAt === -1 ? "" : url.slice(queryAt);
-            // 302 (not 301): a permanent redirect would be cached by the
-            // browser, which is wrong for a dev server whose routes can
-            // change between runs.
-            res.statusCode = 302;
-            res.setHeader("Location", `${pathname}/${query}`);
-            res.end();
-            return;
-          }
-        }
-        next();
-      });
-    },
-  };
-}
-
-// When a `web/` SPA exists, treat it as the dev server's home: the bare
-// `/`, `/__/frontend`, and `/__/frontend/` otherwise 404 (there's no
-// index there), so silently redirect them to `/__/frontend/web/`. Also
-// print the friendlier `http://<host>/` at startup instead of the
-// `/__/frontend/` base URL Vite would otherwise show (which is a dead
-// link).
-function serveWebAppAtRoot(root: string): Plugin {
-  const webIndex = path.resolve(root, "web", "index.html");
-  const target = "/__/frontend/web/";
-  const homes = new Set(["/", "/__/frontend", "/__/frontend/"]);
-  return {
-    name: "reboot-serve-web-app-at-root",
-    configureServer(server) {
-      if (!fs.existsSync(webIndex)) return;
-      server.middlewares.use((req, res, next) => {
-        const url = req.url ?? "";
-        const queryAt = url.indexOf("?");
-        const pathname = queryAt === -1 ? url : url.slice(0, queryAt);
-        if (homes.has(pathname)) {
-          const query = queryAt === -1 ? "" : url.slice(queryAt);
-          res.statusCode = 302;
-          res.setHeader("Location", target + query);
-          res.end();
-          return;
-        }
-        next();
-      });
-      // Print `http://<host>/` instead of the `/__/frontend/` base.
-      const printUrls = server.printUrls.bind(server);
-      server.printUrls = () => {
-        const urls = server.resolvedUrls;
-        if (urls) {
-          const toRoot = (u: string) => u.replace(/\/__\/frontend\/$/, "/");
-          urls.local = urls.local.map(toRoot);
-          urls.network = urls.network.map(toRoot);
-        }
-        printUrls();
-      };
-    },
-  };
-}
-
-// Auto-discover MCP UIs: every `mcp/<name>/` with an `index.html`.
-// There may be no `mcp/` directory at all (a web-only frontend, or
-// one whose last MCP UI was removed), so guard the read.
-const mcpDir = path.resolve(__dirname, "mcp");
-const mcpNames: string[] = fs.existsSync(mcpDir)
-  ? fs
-      .readdirSync(mcpDir)
-      .filter((name) => fs.existsSync(path.resolve(mcpDir, name, "index.html")))
-  : [];
-
-// Path alias for API imports (`@api/...` -> `./api/...`).
-const resolve = {
-  alias: {
-    "@api": path.resolve(__dirname, "./api"),
-  },
-  dedupe: ["react", "react-dom", "zod"],
-};
-
-export default defineConfig(({ command }) => {
-  // Dev server: serves both the MCP UIs and the `web/` SPA.
-  //
-  // UIs use a double iframe architecture:
-  //   MCP Host -> srcdoc (origin=null) -> iframe (origin=localhost:9991)
-  //
-  // The inner iframe loads from Envoy ("/__/frontend/**"), which
-  // proxies to Vite. Because the inner iframe has a real origin,
-  // Vite's URLs work normally. `base: "/__/frontend/"` ensures all
-  // paths route through Envoy.
-  //
-  // The standalone `web/` SPA is served at `/__/frontend/web/` by this
-  // same server. It reaches the backend via `VITE_REBOOT_URL` (see
-  // `web/.env.development`) rather than its own origin, so opening it
-  // straight from this dev server exercises the real cross-origin
-  // frontend/backend path — the same shape as a production deploy.
-  //
-  // Hot Module Replacement works automatically: Vite's client connects
-  // to the page's origin, and Envoy proxies WebSocket upgrades to
-  // Vite. This also works with tunnels (ngrok) since the tunnel
-  // points to Envoy.
-  if (command === "serve") {
-    const port = parseInt(process.env.RBT_VITE_PORT || "4444", 10);
-
-    return {
-      plugins: [
-        react(),
-        redirectFrontendDirTrailingSlash(__dirname),
-        serveWebAppAtRoot(__dirname),
-      ],
-      root: ".",
-      // Read `.env*` from `web/` (alongside the SPA), so the `web/`
-      // SPA's `VITE_REBOOT_URL` is picked up by both this serve and the
-      // `web/` production build, which is also rooted there.
-      envDir: path.resolve(__dirname, "web"),
-      resolve,
-      base: "/__/frontend/",
-      server: {
-        port,
-        strictPort: true,
-        // Listen on all interfaces since requests come through
-        // Envoy (and tunnels).
-        host: true,
-        allowedHosts: true,
-      },
-    };
-  }
-
-  // Which UI a build targets is read from `RBT_BUILD_TARGET` (set by
-  // `build.mjs`), not Vite's `mode` — so `mode` stays `production`
-  // and the `web/` build below reads `web/.env.production`.
-  const target = process.env.RBT_BUILD_TARGET ?? "";
-
-  // Build the standalone `web/` SPA into `dist/web/`. We root the
-  // build at `web/` so `index.html` and its `assets/` land directly
-  // under `dist/web/` (rather than `dist/web/web/`). Keep assets as
-  // separate files (a normal multi-file build) and set `base` so
-  // their URLs resolve when the SPA is served at `/__/frontend/web/`.
-  if (target === "web") {
-    return {
-      plugins: [react()],
-      root: path.resolve(__dirname, "web"),
-      base: "/__/frontend/web/",
-      build: {
-        outDir: path.resolve(__dirname, "dist/web"),
-        emptyOutDir: true,
-      },
-      resolve,
-    };
-  }
-
-  // Build one MCP UI (`RBT_BUILD_TARGET=mcp:<name>`). We root the
-  // build at `mcp/<name>/` so the output lands directly at
-  // `dist/mcp/<name>/index.html`, a single self-contained file
-  // (assets inlined by `vite-plugin-singlefile`). The framework
-  // serves it at `/__/frontend/mcp/<name>/index.html` in dist mode.
-  const name = target.startsWith("mcp:") ? target.slice("mcp:".length) : "";
-  if (!mcpNames.includes(name)) {
-    const valid = mcpNames.map((n) => `mcp:${n}`).join(", ");
-    throw new Error(
-      `Unknown build target: ${target || "(unset)"}. Set ` +
-        `RBT_BUILD_TARGET=web or one of: ${valid}.`
-    );
-  }
-
-  return {
-    plugins: [react(), viteSingleFile()],
-    root: path.resolve(__dirname, "mcp", name),
-    base: "/__/frontend/",
-    // Read `.env*` from `web/` (the shared frontend env), so an MCP UI
-    // can pick up e.g. `VITE_WEB_APP_URL` for a pop-out link.
-    envDir: path.resolve(__dirname, "web"),
-    build: {
-      outDir: path.resolve(__dirname, "dist/mcp", name),
-      emptyOutDir: true,
-      assetsInlineLimit: 100000000,
-      cssCodeSplit: false,
-      rollupOptions: {
-        output: {
-          inlineDynamicImports: true,
-        },
-      },
-    },
-    resolve,
-  };
-});
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Add a standalone web app"
-  description={`
-
-The clicker UI's "Open in web app ↗" button deep-links to a
-standalone browser SPA at \`/__/frontend/web/?counter=<id>\` — the
-same counter, opened full-page outside the AI chat. Create that SPA
-under \`frontend/web/\`: an \`index.html\`, a \`main.tsx\` entry point
-that requires sign-in via \`useUser()\`, and an \`App.tsx\` that lists
-the signed-in user's counters, reads \`?counter=<id>\`, and
-watches/increments a counter with the same generated
-\`useCounter()\` hook.
-
-`}>
-
-```sh
-mkdir -p frontend/web/src
-touch frontend/web/index.html
-touch frontend/web/src/main.tsx frontend/web/src/App.tsx
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/web/index.html&syntax=html) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/web/index.html -->
-
-```html
-<!-- frontend/web/index.html — standalone browser SPA for the
-     ai-chat-counter example. Sign in to create and browse your
-     counters; pass `?counter=<id>` to deep-link a single counter (the
-     MCP clicker's "Open in web app" button lands here). Served from
-     its own origin by the Vite dev server, cross-origin to the
-     backend, which it reaches via `VITE_REBOOT_URL` (see
-     `src/main.tsx`). The same
-     backend also exposes MCP tools, so a user signed in here is
-     automatically signed in on the MCP surface (and vice versa) via
-     shared `rbt_session` cookies. -->
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Chat Counter</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./src/main.tsx"></script>
-  </body>
-</html>
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/get_started_main.tsx&syntax=tsx) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/get_started_main.tsx -->
-
-```tsx
-// frontend/web/src/main.tsx
-import { useUser } from "@api/ai_chat_counter/v1/counter_rbt_react";
-import {
-  RebootClientProvider,
-  useSignIn,
-  useSignOut,
-} from "@reboot-dev/reboot-react";
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import { App } from "./App";
-
-const Root = () => {
-  const { user, isLoading } = useUser();
-  const signIn = useSignIn();
-  const signOut = useSignOut();
-  // The provider renders us immediately and resolves the signed-in
-  // user in the background, so we see `isLoading` until `/whoami`
-  // lands.
-  if (isLoading) {
-    return <main className="loading">Checking session…</main>;
-  }
-  if (user === undefined) {
-    return (
-      <main className="signin-prompt">
-        <h1>Chat Counter</h1>
-        <p>Sign in to create and browse your counters.</p>
-        <button onClick={() => signIn()}>Sign in</button>
-      </main>
-    );
-  }
-  return <App user={user} onSignOut={() => void signOut()} />;
-};
-
-// Point the Reboot client at the backend via `VITE_REBOOT_URL`. A web
-// app is served from its own origin — a CDN or static host — almost
-// never same-origin with the Reboot backend, so a real deploy MUST set
-// `VITE_REBOOT_URL` to the backend's origin. `web/.env.development`
-// sets it for local dev (to the Envoy endpoint), so this SPA runs on
-// the Vite dev server cross-origin to the backend — the same shape as
-// production.
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <RebootClientProvider url={import.meta.env.VITE_REBOOT_URL}>
-      <Root />
-    </RebootClientProvider>
-  </StrictMode>
-);
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/web/src/App.tsx&syntax=tsx) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/web/src/App.tsx -->
-
-```tsx
-// frontend/web/src/App.tsx
-import {
-  type UseCounterApi,
-  type UseUserApi,
-  useCounter,
-} from "@api/ai_chat_counter/v1/counter_rbt_react";
-import { useState, type FC } from "react";
-
-interface AppProps {
-  user: UseUserApi;
-  onSignOut: () => void;
-}
-
-// Read an initial counter ID from the `?counter=<id>` query param so a
-// counter can be shared via URL — the MCP clicker's "Open in web app"
-// button deep-links here; picking a counter from the list below also
-// opens it.
-const initialCounterId = (): string =>
-  new URLSearchParams(window.location.search).get("counter") ?? "";
-
-export const App: FC<AppProps> = ({ user, onSignOut }) => {
-  const [counterId, setCounterId] = useState(initialCounterId);
-
-  return (
-    <main className="shell">
-      <header className="header">
-        <h1>Chat Counter</h1>
-        <div className="identity">
-          <code>{user.state_id}</code>
-          <button className="ghost" onClick={onSignOut}>
-            Sign out
-          </button>
-        </div>
-      </header>
-
-      {counterId.length === 0 ? (
-        <CounterList user={user} onOpen={setCounterId} />
-      ) : (
-        <>
-          <button
-            className="ghost back"
-            onClick={() => {
-              // Drop any `?counter=<id>` from the URL so a reload
-              // stays on the list.
-              window.history.replaceState(null, "", window.location.pathname);
-              setCounterId("");
-            }}
-          >
-            ← All counters
-          </button>
-          <CounterView key={counterId} counterId={counterId} />
-        </>
-      )}
-    </main>
-  );
-};
-
-// Landing view: create a counter, and open one of the signed-in
-// user's own counters (read reactively via `User.list_counters`).
-const CounterList: FC<{ user: UseUserApi; onOpen: (id: string) => void }> = ({
-  user,
-  onOpen,
-}) => {
-  const { response: listResponse, isLoading } = user.useListCounters();
-  const [description, setDescription] = useState("");
-  const [pending, setPending] = useState(false);
-
-  const handleCreate = async () => {
-    if (description.trim().length === 0) return;
-    setPending(true);
-    try {
-      await user.createCounter({ description });
-      setDescription("");
-    } finally {
-      setPending(false);
-    }
-  };
-
-  const counters = listResponse?.counters ?? [];
-  const showLoading = isLoading && listResponse === undefined;
-
-  return (
-    <>
-      <section className="card">
-        <h2>Create counter</h2>
-        <form
-          className="create-row"
-          onSubmit={(event) => {
-            event.preventDefault();
-            void handleCreate();
-          }}
-        >
-          <input
-            value={description}
-            onChange={(event) => setDescription(event.target.value)}
-            placeholder="What does this counter count?"
-          />
-          <button type="submit" disabled={pending}>
-            Create
-          </button>
-        </form>
-      </section>
-
-      <section className="card">
-        <h2>Your counters</h2>
-        {showLoading ? (
-          <p className="empty">Loading…</p>
-        ) : counters.length === 0 ? (
-          <p className="empty">No counters yet — create one above.</p>
-        ) : (
-          <ul className="counters">
-            {counters.map((counter) => (
-              <li key={counter.counterId} className="counter">
-                <button
-                  className="counter-open"
-                  onClick={() => onOpen(counter.counterId)}
-                >
-                  <span className="counter-description">
-                    {counter.description}
-                  </span>
-                  <code className="counter-id">{counter.counterId}</code>
-                </button>
-              </li>
-            ))}
-          </ul>
-        )}
-      </section>
-    </>
-  );
-};
-
-const CounterView: FC<{ counterId: string }> = ({ counterId }) => {
-  // The generated zod hook returns the `UseCounterApi` directly; reads
-  // are exposed as nested `use*` hooks and writes as plain methods.
-  const counter: UseCounterApi = useCounter({ id: counterId });
-  const { response: valueResponse, isLoading } = counter.useGet();
-  const { response: descriptionResponse } = counter.useDescription();
-  const [pending, setPending] = useState(false);
-
-  // Show a muted placeholder until the description loads rather than
-  // flashing the "(no description)" fallback first.
-  const descriptionLoading = descriptionResponse === undefined;
-
-  const handleIncrement = async () => {
-    setPending(true);
-    try {
-      await counter.increment({ amount: 1 });
-    } finally {
-      setPending(false);
-    }
-  };
-
-  return (
-    <section className="card counter-detail">
-      <p
-        className={
-          "counter-detail-description" + (descriptionLoading ? " muted" : "")
-        }
-      >
-        {descriptionLoading
-          ? "Loading…"
-          : descriptionResponse?.description || "(no description)"}
-      </p>
-      <div className="counter-detail-value">
-        {isLoading && valueResponse === undefined
-          ? "…"
-          : valueResponse?.value ?? 0}
-      </div>
-      <button onClick={handleIncrement} disabled={pending}>
-        {pending ? "Incrementing…" : "Increment"}
-      </button>
-    </section>
-  );
-};
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title={<div>Configure your <code>.rbtrc</code></div>}
-  description={`
-
-An [\`.rbtrc\`](/develop_locally#rbtrc-and-flags) file contains flags
-for the \`rbt\` CLI. Use it to tell Reboot where your API files live,
-how to generate code, and how to run your app.
-
-The key addition for AI Chat Apps is
-\`generate --react=frontend/api\`, which generates the React hooks
-the UI uses.
-
-`}>
-
-```sh
-touch .rbtrc
-```
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/.rbtrc&lines=1-36&syntax=sh) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/.rbtrc -->
-
-```sh
-# .rbtrc
-# Find API definitions in 'api/'.
-generate api/
-
-# Generate Python code.
-generate --python=backend/api/
-
-# Generate React hooks.
-generate --react=frontend/api
-
-# Watch for source changes.
-dev run --watch=backend/**/*.py
-dev run --watch=frontend/dist/**/*.html
-
-# Python application.
-dev run --python
-
-# Save state between restarts.
-dev run --application-name=ai-chat-counter
-
-# Entrypoint.
-dev run --application=backend/src/main.py
-
-# Default to HMR mode when no --config is specified.
-dev run --default-config=hmr
-
-# Hot Module Replacement (HMR): Vite dev server proxied through Envoy.
-# Run Vite in a separate terminal: `cd frontend && npm run dev`
-dev run --frontend-root-path=frontend
-
-dev run:hmr --frontend-host=http://localhost:4444
-
-# Dist mode: serve pre-built artifacts from "frontend/dist/" (no Vite HMR).
-# Usage: `uv run rbt dev run --config=dist`
-# Requires: `cd frontend && npm run build`
-dev run:dist --frontend-dist-path=frontend/dist
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-</Step>
-<Step
-  title="Build your frontend"
-  description={`
-
-Bundle both frontends: the clicker UI (served as an MCP resource
-when the AI calls the \`show_clicker\` tool) and the standalone
-\`web/\` SPA (the pop-out target). You need to run
-\`uv run rbt dev run\` first so that the generated React hooks
-are available.
-
-
-`}>
-
-```sh
-uv run rbt dev run &
-cd frontend
-RBT_BUILD_TARGET=mcp:clicker npx vite build
-RBT_BUILD_TARGET=web npx vite build
-```
-
-</Step>
-<Step
-  title="Run your app"
-  description={`
-
-If you ran \`rbt dev run\` in the background above, stop it and restart it in dist mode
-to serve your freshly built UI. Otherwise, start it in dist mode
-now.
-
-`}>
-
-```sh
-uv run rbt dev run --config=dist
-```
-
-</Step>
-<Step
-  title="Test with MCPJam Inspector"
-  description={`
-
-Run MCPJam Inspector to interact with your app.
-
-`}>
-
-```sh
-npx @mcpjam/inspector@2.23.3 --url http://localhost:9991/mcp --oauth
-```
-
-</Step>
-</CodeStepByStep>
-
-<!-- TODO: use e.g. `## Next steps` instead of `<h1>Next steps</h1>`
-once we figure out to hide the right side navigation/table
-of contents. -->
-
-<h1>How to try out your app</h1>
-
-MCPJam opens a browser-based interface where you can test your app's
-tools and UIs.
-
-Click **App Builder** in the left sidebar. You should see tools
-including `create_counter`, `counter_get`,
-`counter_increment`, and `counter_show_clicker`.
-
-1. Select **`counter_show_clicker`** and click **Run** to show your UI. You
-   should be able to increment the counter by clicking a button.
-2. If you are signed in to MCPJam you can additionally ask the LLM to
-   take actions for you in conversation, like your users will. Try
-   prompts like...
-   * "show me my clicker UI"
-   * "increment my counter"
-3. As you interact with the UI, notice how actions taken outside the UI
-   (e.g. asking the LLM to increment the counter) update the UI
-   reactively.
-
-Under the hood, your app communicates via MCP (Model Context Protocol),
-the standard that AI clients like ChatGPT, Claude, and VS Code use to
-discover and interact with apps.
-
-<h1>Next steps</h1>
-
-Well done! You have a working AI Chat App. Here are some great
-next steps:
-
-* **[UIs for AI Chat Apps](/learn_more/implement/ui_methods)** — the
-  full reference for `UI` methods, including parameterized UIs where
-  the AI passes props to the React component.
-* **[Creating tools](/learn_more/define/pydantic#creating-tools-for-the-ai)** —
-  how to control which methods are callable by the AI, including
-  exposing methods on non-`User` state types, or hiding some
-  `User` methods from the AI.
-* **[How Reboot uses MCP](/learn_more/mcp_apps)** — learn how
-  AI Chat Apps work under the hood.
-* **[AI Chat App Examples](/ai_chat_apps/examples)**
-  — more examples to explore.
-* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — deploy
-  your app with `rbt cloud up`.
-* **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** — to
-  ask questions and let us know what you think!
diff --git a/documentation/docs/ai_chat_apps/get_started_claude_code.mdx b/documentation/docs/ai_chat_apps/get_started_claude_code.mdx
deleted file mode 100644
index f6cea39cc..000000000
--- a/documentation/docs/ai_chat_apps/get_started_claude_code.mdx
+++ /dev/null
@@ -1,205 +0,0 @@
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Get Started (with Claude Code)
-
-Build an AI Chat App using
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
-and the Reboot plugin. Claude Code writes the code for you — you
-describe what you want, approve the plan, and it scaffolds the
-entire project.
-
-## Install the Reboot plugin
-
-The plugin bundles everything Reboot needs, so
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
-itself is the only thing you need to have installed.
-
-<Tabs groupId="install-method">
-  <TabItem value="quick" label="Quick install">
-
-Install the Reboot plugin for Claude Code with a single
-command:
-
-```sh
-curl -fsSL https://reboot.dev/install.sh | bash
-```
-
-This registers the Reboot marketplace, installs the plugin,
-and pre-installs its pinned dependencies so your first build
-runs without waiting on downloads.
-
-Then start Claude Code — or, if it was already running while you
-installed, restart it — so the plugin loads.
-
-  </TabItem>
-  <TabItem value="manual" label="Manual install">
-
-Add the marketplace and install the plugin yourself with
-Claude Code:
-
-```
-claude plugin marketplace add reboot-dev/reboot-plugin
-```
-
-```
-claude plugin install reboot@reboot-plugin
-```
-
-Or, to auto-enable the plugin for your whole team, add this to your
-project's `.claude/settings.json`:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "reboot-plugin": {
-      "source": {
-        "source": "github",
-        "repo": "reboot-dev/reboot-plugin"
-      }
-    }
-  },
-  "enabledPlugins": {
-    "reboot@reboot-plugin": true
-  }
-}
-```
-
-Restart any Claude Code session that was already running when you
-installed the Reboot plugin so the new plugin loads.
-
-  </TabItem>
-</Tabs>
-
-## Use the skill
-
-Once installed, invoke the skill with a description of your app:
-
-```
-/reboot:chat-app Build a counter app with an interactive clicker UI
-```
-
-You can also just describe what you want to build in a normal
-prompt — Claude Code selects the right Reboot skill from your
-description. Or invoke `/reboot:app`, which asks whether you want
-an AI Chat App or a standalone Web App and then hands off to the
-matching skill — for this guide, pick the Chat App.
-
-The skill settles the design before it writes any code. It will:
-
-1. Analyze your description and propose a state model
-2. Map out which types, methods, AI tools, and UIs your app needs
-3. State that design back to you — so you can redirect it before
-   the code exists
-
-Claude Code then scaffolds the full project — API definition,
-backend servicers, React UI, and configuration — builds it, writes
-and runs backend tests, and starts the app.
-
-## What gets created
-
-The skill generates a complete Reboot AI Chat App. The most relevant
-files are:
-
-```
-my-app/
-├── .rbtrc                    # Reboot CLI config
-├── pyproject.toml            # Python deps (uv)
-├── api/
-│   └── my_app/v1/
-│       └── my_app.py         # API definition (Pydantic)
-├── backend/
-│   ├── api/                  # Generated Python bindings
-│   ├── src/
-│   │   ├── main.py           # Application entrypoint
-│   │   ├── example_prompts.py  # Setup wizard example prompts
-│   │   └── servicers/
-│   │       └── my_app.py     # Servicer implementation
-│   └── tests/
-│       └── my_app_test.py    # Backend behavior tests
-└── frontend/
-    ├── package.json
-    ├── build.mjs            # Discovers + builds every UI
-    ├── vite.config.ts
-    ├── api/                 # Generated React bindings (rbt generate)
-    ├── mcp/
-    │   └── my-ui/
-    │       ├── index.html
-    │       ├── index.css        # Styling
-    │       ├── main.tsx         # RebootClientProvider entry
-    │       ├── App.tsx          # React component
-    │       └── App.module.css
-    └── web/                 # Optional standalone browser SPA
-        ├── index.html
-        └── src/
-            ├── main.tsx
-            └── App.tsx
-```
-
-The API definition uses the same `User` + application type
-pattern described in the
-[hand-written guide](/ai_chat_apps/get_started): `User` is the
-auto-constructed entry point whose methods create other state
-types, and those types' methods use `mcp=Tool()` to be callable
-by the AI. UI methods use `UI()` and render React inside the MCP
-host.
-
-## Test your app
-
-Claude Code writes backend unit tests covering your app's user
-stories and runs them before handing the app off — they help to
-make sure that your app works, and keeps working.
-
-Once the tests pass, Claude Code starts everything the app needs:
-
-* the Reboot backend (`rbt dev run`), which also serves the MCP
-  endpoint,
-* the Vite frontend dev server, and
-* a Cloudflare quick tunnel, so that remote MCP clients (like
-  ChatGPT) can reach your local app.
-
-It then opens the app's **setup wizard** at `http://localhost:9991`
-— a page served by your app that walks you through connecting an
-MCP client (Claude, ChatGPT, or the MCPJam Inspector) and suggests
-example prompts to try.
-
-## Iterate on your app
-
-You can also use the skill to modify an existing app:
-
-```
-/reboot:chat-app Add a reset button that sets the counter back to zero
-```
-
-The skill reads your current code, plans the changes, and waits
-for approval before editing.
-
-## Run it again later
-
-If you come back to your project in a new session, ask Claude Code
-to bring the app back up:
-
-```
-/reboot:run my-app
-```
-
-Or just say "Run this Reboot app" from the project directory. The
-run skill starts everything your app needs and reopens the setup
-wizard.
-
-## Next steps
-
-* **[Get Started (with Codex)](/ai_chat_apps/get_started_codex)** —
-  the equivalent agent-driven workflow for Codex.
-* **[Get Started (hand-written)](/ai_chat_apps/get_started)** —
-  build the same app step by step to understand every file.
-* **[UIs for AI Chat Apps](/learn_more/implement/ui_methods)** —
-  the full reference for `UI` methods.
-* **[Creating tools](/learn_more/define/pydantic#creating-tools-for-the-ai)** —
-  control which methods are callable by the AI.
-* **[AI Chat App Examples](/ai_chat_apps/examples)** — more
-  examples to explore.
-* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — deploy
-  your app with `rbt cloud up`.
-* **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** — ask
-  questions and share what you're building!
diff --git a/documentation/docs/ai_chat_apps/get_started_codex.mdx b/documentation/docs/ai_chat_apps/get_started_codex.mdx
deleted file mode 100644
index 12d717773..000000000
--- a/documentation/docs/ai_chat_apps/get_started_codex.mdx
+++ /dev/null
@@ -1,225 +0,0 @@
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Get Started (with Codex)
-
-Build an AI Chat App using [Codex](https://developers.openai.com/codex/)
-and the Reboot plugin. Codex writes the code for you: describe the app,
-approve the proposed design, and it scaffolds the Reboot backend,
-interactive UI, tests, and local development setup.
-
-## Install the Reboot plugin
-
-The plugin bundles everything Reboot needs, so the only prerequisite is
-[Codex](https://developers.openai.com/codex/cli) itself (installed and
-authenticated).
-
-<Tabs groupId="install-method">
-  <TabItem value="quick" label="Quick install">
-
-Install the Reboot plugin for Codex with a single command:
-
-```sh
-curl -fsSL https://reboot.dev/install.sh | bash
-```
-
-The installer detects Codex, registers the Reboot plugin marketplace,
-installs the plugin, enables Codex hooks, and pre-installs the pinned
-tool shims used by the skill.
-
-:::warning Temporary Codex sandbox opt-out
-The installer currently asks to disable Codex's sandbox globally by
-writing `sandbox_mode = "danger-full-access"` into
-`~/.codex/config.toml`. This is a temporary workaround for an upstream
-Codex issue that breaks Python asyncio cross-thread wakeups inside the
-sandbox. Reboot's main commands (`rbt generate`, `rbt dev run`, and
-related commands) rely on that asyncio behavior.
-
-If you accept the prompt, the installer tags the setting with a
-`# reboot-plugin (managed)` comment so it is easy to find and remove
-later. If you decline, the Codex install is skipped because the
-plugin's main commands will not work reliably under the current
-sandbox behavior.
-:::
-
-Restart Codex after installation so the new plugin, skills, hooks, and
-PATH configuration are loaded.
-
-  </TabItem>
-  <TabItem value="manual" label="Manual install">
-
-Register the Reboot plugin marketplace and install the plugin yourself:
-
-```sh
-codex plugin marketplace add reboot-dev/reboot-plugin
-```
-
-```sh
-codex plugin add reboot@reboot-plugin
-```
-
-Then add the required Codex settings to `~/.codex/config.toml`. Codex
-prints the plugin install path in `codex plugin list`; use it to build
-the PATH entry for your machine:
-
-```sh
-REBOOT_PLUGIN_ROOT="$(codex plugin list \
-  | awk '$1 == "reboot@reboot-plugin" {print $NF; exit}')"
-
-printf 'features.hooks = true\n'
-printf 'shell_environment_policy.set.PATH = "%s/bin:%s"\n' \
-  "$REBOOT_PLUGIN_ROOT" "$PATH"
-printf 'sandbox_mode = "danger-full-access"\n'
-```
-
-Copy the output into `~/.codex/config.toml`, at the **top** of the
-file (dotted keys pasted below a `[table]` header would become part of
-that table). It should look like this, with your actual plugin path:
-
-```toml
-features.hooks = true
-shell_environment_policy.set.PATH = "/path/from/codex/plugin/list/bin:/your/existing/path"
-sandbox_mode = "danger-full-access"
-```
-
-:::warning Merge with your existing config
-TOML forbids defining the same key or table twice, and Codex refuses
-to start on such a config ("duplicate key"). If your config already
-has a `[features]` or `[shell_environment_policy]` table, or already
-sets `sandbox_mode`, set the values inside your existing tables
-instead of pasting the dotted keys above — e.g. add `hooks = true`
-under your `[features]` table.
-:::
-
-Restart Codex after changing the config.
-
-  </TabItem>
-</Tabs>
-
-## Use the skill
-
-In Codex, you do not need a slash command. Start from a normal prompt:
-
-```
-Build a Reboot counter AI chat app with an interactive clicker UI
-```
-
-Codex selects the Reboot app skill from the prompt and routes to the AI
-Chat App builder. The builder settles the design before it writes any
-code. It will:
-
-1. Analyze your description and propose a state model.
-2. Map out the `User` entry point, application types, methods, AI tools,
-   and UIs.
-3. State that design back to you — so you can redirect it before the
-   code exists.
-
-Codex then scaffolds the full project — API definition, backend
-servicers, React UI, and configuration — builds it, writes and runs
-backend tests, and starts the app.
-
-## What gets created
-
-The skill generates a complete Reboot AI Chat App. The most relevant
-files are:
-
-```
-my-app/
-├── .rbtrc                    # Reboot CLI config
-├── pyproject.toml            # Python deps (uv)
-├── api/
-│   └── my_app/v1/
-│       └── my_app.py         # API definition (Pydantic)
-├── backend/
-│   ├── api/                  # Generated Python bindings
-│   ├── src/
-│   │   ├── main.py           # Application entrypoint
-│   │   ├── example_prompts.py  # Setup wizard example prompts
-│   │   └── servicers/
-│   │       └── my_app.py     # Servicer implementation
-│   └── tests/
-│       └── my_app_test.py    # Backend behavior tests
-└── frontend/
-    ├── package.json
-    ├── build.mjs            # Discovers + builds every UI
-    ├── vite.config.ts
-    ├── api/                 # Generated React bindings (rbt generate)
-    ├── mcp/
-    │   └── my-ui/
-    │       ├── index.html
-    │       ├── index.css        # Styling
-    │       ├── main.tsx         # RebootClientProvider entry
-    │       ├── App.tsx          # React component
-    │       └── App.module.css
-    └── web/                 # Optional standalone browser SPA
-        ├── index.html
-        └── src/
-            ├── main.tsx
-            └── App.tsx
-```
-
-The API definition uses the same `User` + application type pattern
-described in the [hand-written guide](/ai_chat_apps/get_started):
-`User` is the auto-constructed entry point whose methods create other
-state types, and those types' methods use `mcp=Tool()` to be callable
-by the AI. UI methods use `UI()` and render React inside the MCP host.
-
-## Test your app
-
-Codex writes backend unit tests covering your app's user
-stories and runs them before handing the app off — they help to
-make sure that your app works, and keeps working.
-
-Once the tests pass, Codex starts everything the app needs:
-
-* the Reboot backend (`rbt dev run`), which also serves the MCP
-  endpoint,
-* the Vite frontend dev server, and
-* a Cloudflare quick tunnel, so that remote MCP clients (like
-  ChatGPT) can reach your local app.
-
-It then opens the app's **setup wizard** at `http://localhost:9991`
-— a page served by your app that walks you through connecting an
-MCP client (Claude, ChatGPT, or the MCPJam Inspector) and suggests
-example prompts to try.
-
-## Iterate on your app
-
-You can use the same skill to modify an existing app:
-
-```
-Add a reset button that sets the counter back to zero.
-```
-
-Codex reads the current Reboot project, proposes a plan, waits for your
-approval, then updates the API, servicers, React UI, and tests.
-
-## Run it again later
-
-If you close Codex and come back to the project later, ask Codex to run
-the Reboot app again:
-
-```
-Run my Reboot app in ./my-app
-```
-
-Or just say "Run this Reboot app" from the project directory. The
-run skill starts everything your app needs and reopens the setup
-wizard.
-
-## Next steps
-
-* **[Get Started (with Claude Code)](/ai_chat_apps/get_started_claude_code)** —
-  the equivalent agent-driven workflow for Claude Code.
-* **[Get Started (hand-written)](/ai_chat_apps/get_started)** —
-  build the same app step by step to understand every file.
-* **[UIs for AI Chat Apps](/learn_more/implement/ui_methods)** —
-  the full reference for `UI` methods.
-* **[Creating tools](/learn_more/define/pydantic#creating-tools-for-the-ai)** —
-  control which methods are callable by the AI.
-* **[AI Chat App Examples](/ai_chat_apps/examples)** — more examples
-  to explore.
-* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — deploy your
-  app with `rbt cloud up`.
-* **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** — ask
-  questions and share what you're building!
diff --git a/documentation/docs/ai_chat_apps/what_is.mdx b/documentation/docs/ai_chat_apps/what_is.mdx
deleted file mode 100644
index afd5842be..000000000
--- a/documentation/docs/ai_chat_apps/what_is.mdx
+++ /dev/null
@@ -1,196 +0,0 @@
-# What is an AI Chat App?
-
-AI Chat Apps are visual, reactive, stateful apps that run inside AI chat
-user interfaces — ChatGPT, Claude, VS Code, Goose, and more. 
-
-Instead of text-only responses, the AI opens **interactive React
-UIs** directly in the conversation. Your users click buttons,
-fill forms, and see live-updating data — all without leaving the
-chat.
-
-AI Chat Apps are composed of a user interface, backend methods for both
-the AI and UI to call, and durable state types that provide the
-persistent data your app is built around.
-
-## Why AI Chat Apps?
-
-Text-only AI is already dated. Users expect rich, interactive
-experiences. With Reboot, AI Chat Apps let you:
-
-- **Show, don't tell.** Open a visual UI right in your user's chat.
-- **React to state changes.** Your UIs update in real time as
-  backend state changes — whether the user, the AI, or another
-  client made the change.
-- **Persist across sessions.** State is durable. Close the chat,
-  come back later, and everything is still there.
-
-## How it works
-
-In Reboot, you define your chat app with three things:
-
-1. **`UI` methods** — React components that the AI can open in the
-   chat interface. Your React `App.tsx` is the implementation. These
-   connect to business logic and data via...
-2. **Backend Methods** — for your UI and/or your AI to call. In Reboot,
-   these come as [`reader`](/learn_more/implement/readers),
-   [`writer`](/learn_more/implement/writers),
-   [`transaction`](/learn_more/implement/transactions), and
-   [`workflow`](/learn_more/implement/workflows) methods, providing
-   safety and scalability.
-3. **Durable state types** — these are like Python classes, but their
-   state is automatically persisted. Use these to store the data your
-   app needs - no external database. This is also where the backend
-   methods live; they operate on your app's durable state directly.
-
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
-
-```python
-# api/ai_chat_counter/v1/counter.py
-from reboot.api import (
-    API,
-    UI,
-    Field,
-    Methods,
-    Model,
-    Reader,
-    Tool,
-    Transaction,
-    Type,
-    Writer,
-)
-
-
-class CreateCounterRequest(Model):
-    description: str = Field(tag=1)
-
-
-class CreateCounterResponse(Model):
-    counter_id: str = Field(tag=1)
-
-
-class CounterEntry(Model):
-    counter_id: str = Field(tag=1)
-    description: str = Field(tag=2)
-
-
-class ListCountersResponse(Model):
-    counters: list[CounterEntry] = Field(tag=1, default_factory=list)
-
-
-class UserState(Model):
-    counter_ids: list[str] = Field(tag=1, default_factory=list)
-
-
-class InitializeCounterRequest(Model):
-    description: str = Field(tag=1)
-    # The `user_id` of the Counter's owner, recorded so that only the
-    # owner may call the Counter later.
-    owner_id: str = Field(tag=2)
-
-
-class DescriptionResponse(Model):
-    description: str = Field(tag=1)
-
-
-class CounterState(Model):
-    value: int = Field(tag=1, default=0)
-    description: str = Field(tag=2, default="")
-    owner_id: str = Field(tag=3, default="")
-
-
-class GetResponse(Model):
-    value: int = Field(tag=1)
-
-
-class IncrementRequest(Model):
-    """Request with an amount parameter."""
-    amount: int | None = Field(tag=1, default=None)
-
-
-api = API(
-    User=Type(
-        state=UserState,
-        methods=Methods(
-            create_counter=Transaction(
-                request=CreateCounterRequest,
-                response=CreateCounterResponse,
-                description="Create a new Counter with a "
-                "description of what it counts. Returns "
-                "the `counter_id`, which is not "
-                "human-readable but should be passed to "
-                "future tool calls that need it.",
-                mcp=Tool(),
-            ),
-            list_counters=Reader(
-                request=None,
-                response=ListCountersResponse,
-                description="List all counters created "
-                "by this user. Returns `counter_id` and "
-                "description for each. The `counter_id` "
-                "is not human-readable, but use it when "
-                "calling tools that take a `counter_id`.",
-                mcp=Tool(),
-            ),
-        ),
-    ),
-    Counter=Type(
-        state=CounterState,
-        methods=Methods(
-            show_clicker=UI(
-                request=None,
-                path="frontend/mcp/clicker",
-                title="Counter Clicker",
-                description="Interactive clicker UI "
-                "for the counter.",
-            ),
-            create=Writer(
-                request=InitializeCounterRequest,
-                response=None,
-                factory=True,
-                description="Create the counter at its initial value.",
-                mcp=None,
-            ),
-            get=Reader(
-                request=None,
-                response=GetResponse,
-                description="Get the current counter "
-                "value.",
-                mcp=Tool(),
-            ),
-            increment=Writer(
-                request=IncrementRequest,
-                response=None,
-                description="Increment the counter by "
-                "the specified amount.",
-                mcp=Tool(),
-            ),
-            description=Reader(
-                request=None,
-                response=DescriptionResponse,
-                mcp=None,
-            ),
-        ),
-    ),
-)
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-Use `mcp=Tool()` on every method you want the AI to call,
-including `User` methods. Methods on other types (like `Counter`)
-that expose `mcp=Tool()` operate on a specific instance: the AI
-receives the instance's state ID when the instance is created
-(here, the `counter_id` returned by `create_counter`) and passes
-it in subsequent calls.
-
-Under the hood, AI Chat Apps use [MCP (the Model Context
-Protocol)](/learn_more/mcp_apps) — the standard that AI clients use to
-discover and interact with external apps.
-
-
-## Get started
-
-Ready to build one?
-
-**[Build your first AI Chat App →](/ai_chat_apps/get_started)**
diff --git a/documentation/docs/learn_more/call/from_mcp_client.mdx b/documentation/docs/call/from_mcp_client.mdx
similarity index 96%
rename from documentation/docs/learn_more/call/from_mcp_client.mdx
rename to documentation/docs/call/from_mcp_client.mdx
index 8b842670b..693b7a84d 100644
--- a/documentation/docs/learn_more/call/from_mcp_client.mdx
+++ b/documentation/docs/call/from_mcp_client.mdx
@@ -43,7 +43,7 @@ This opens MCPJam in your browser (if no tab opens, visit
 [http://localhost:6274](http://localhost:6274)), pointed straight at
 your app's MCP endpoint with OAuth enabled. From there you can browse
 your app's tools, call them, and see
-[`UI`](/learn_more/implement/ui_methods) method React apps rendered
+[`UI`](/surfaces/ui_methods) method React apps rendered
 inline.
 
 ## Set up a secure tunnel
@@ -95,7 +95,7 @@ its URL for you.
 
 :::warning Free ngrok tunnels don't work with Claude
 
-Claude renders [`UI`](/learn_more/implement/ui_methods) methods as
+Claude renders [`UI`](/surfaces/ui_methods) methods as
 HTML with `<script>` tags, and free ngrok tunnels
 (`*.ngrok-free.dev`) serve an HTML interstitial on first request that
 breaks those scripts. When testing with Claude, use `cloudflared` (or
@@ -155,7 +155,7 @@ for how to enable it.
    (**User Profile → Settings → Apps → Advanced Settings**), then
    click **Create App**.
 2. Enter the name, a description, and the MCP URL. If your app uses
-   auth ([`Development`](/learn_more/identity_and_external_apis) or
+   auth ([`Development`](/users/providers#development) or
    otherwise), select **OAuth** from the Authentication dropdown —
    ChatGPT will run the OAuth handshake as soon as you add the server.
    Otherwise, select **No auth**.
diff --git a/documentation/docs/learn_more/call/from_outside_your_app.mdx b/documentation/docs/call/from_outside_your_app.mdx
similarity index 89%
rename from documentation/docs/learn_more/call/from_outside_your_app.mdx
rename to documentation/docs/call/from_outside_your_app.mdx
index ea4bc02ca..7d291a510 100644
--- a/documentation/docs/learn_more/call/from_outside_your_app.mdx
+++ b/documentation/docs/call/from_outside_your_app.mdx
@@ -54,12 +54,12 @@ atomicity guarantees with regard to one another (although the
 individual methods executing within Reboot will of course still have
 their own atomicity). If you are calling multiple Reboot methods that
 you would like to happen atomically, you can move those calls into a
-[`transaction`](/learn_more/define/methods#kinds), and then
+[`transaction`](/define/methods#kinds), and then
 call that method from your client.
 
 ## Making calls idempotently
 
-You can make calls [`idempotently()`](/learn_more/idempotency)
+You can make calls [`idempotently()`](/idempotency)
 using an `ExternalContext` so
 that you only perform operations once. You can even pass an
 _idempotency seed_, e.g., a `UUID`, to an `ExternalContext` when
@@ -102,8 +102,8 @@ changes. For example:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/demos/fig/backend/src/many_readers.py&lines=20-22) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/demos/fig/backend/src/many_readers.py -->
+(CODE:src=../../../reboot/demos/fig/backend/src/many_readers.py&lines=20-22) -->
+<!-- The below code snippet is automatically added from ../../../reboot/demos/fig/backend/src/many_readers.py -->
 
 ```py
 fig = Fig.ref(fig_id)
@@ -126,8 +126,8 @@ async for response in fig.reactively().get_position(context):
 
 When calling multiple Reboot methods externally, you can use the
 same concurrency patterns described in
-[Making concurrent calls](/learn_more/call/from_within_your_app#making-concurrent-calls).
+[Making concurrent calls](/call/from_within_your_app#making-concurrent-calls).
 For Python, the `concurrently` helper provides adaptive
 concurrency limits and streaming results — see
-[`concurrently` (Python)](/learn_more/call/from_within_your_app#concurrently-python)
+[`concurrently` (Python)](/call/from_within_your_app#concurrently-python)
 for details and examples.
diff --git a/documentation/docs/learn_more/call/from_react.mdx b/documentation/docs/call/from_react.mdx
similarity index 77%
rename from documentation/docs/learn_more/call/from_react.mdx
rename to documentation/docs/call/from_react.mdx
index 1120593ed..739bcec37 100644
--- a/documentation/docs/learn_more/call/from_react.mdx
+++ b/documentation/docs/call/from_react.mdx
@@ -9,14 +9,14 @@ easily query and mutate Reboot data types.
 ## Overview
 
 Consider a `ChatRoom` API definition with one data type, `ChatRoom`, one
-[`reader`](/learn_more/define/methods#kinds), and one
-[`writer`](/learn_more/define/methods#kinds) method.
+[`reader`](/define/methods#kinds), and one
+[`writer`](/define/methods#kinds) method.
 
 <Tabs groupId="language">
   <TabItem value="typescript" label="Zod" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/chat_room_zod.ts&lines=1-28) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/chat_room_zod.ts -->
+(CODE:src=../../../tests/reboot/documentation/chat_room_zod.ts&lines=1-28) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/chat_room_zod.ts -->
 
 ```ts
 import { reader, writer } from "@reboot-dev/reboot-api";
@@ -53,8 +53,8 @@ export const api = {
   </TabItem>
   <TabItem value="python" label="Pydantic">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/chat_room_pydantic.py&lines=1-39) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/chat_room_pydantic.py -->
+(CODE:src=../../../tests/reboot/documentation/chat_room_pydantic.py&lines=1-39) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/chat_room_pydantic.py -->
 
 ```py
 from reboot.api import API, Field, Methods, Model, Reader, Type, Writer
@@ -98,47 +98,6 @@ api = API(
 )
 ```
 
-<!-- MARKDOWN-AUTO-DOCS:END -->
-  </TabItem>
-  <TabItem value="proto" label="Proto">
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/api/chat_room/v1/chat_room.proto&&lines=9-41&syntax=protobuf) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/api/chat_room/v1/chat_room.proto -->
-
-```protobuf
-message ChatRoom {
-  option (rbt.v1alpha1.state) = {
-  };
-  repeated string messages = 1;
-}
-
-service ChatRoomMethods {
-  // Returns the current list of recorded messages.
-  rpc Messages(MessagesRequest) returns (MessagesResponse) {
-    option (rbt.v1alpha1.method).reader = {
-    };
-  }
-
-  // Adds a new message to the list of recorded messages.
-  rpc Send(SendRequest) returns (SendResponse) {
-    option (rbt.v1alpha1.method).writer = {
-    };
-  }
-}
-
-message MessagesRequest {}
-
-message MessagesResponse {
-  repeated string messages = 1;
-}
-
-message SendRequest {
-  string message = 1;  // E.g. "Hello, World".
-}
-
-message SendResponse {}
-```
-
 <!-- MARKDOWN-AUTO-DOCS:END -->
   </TabItem>
 </Tabs>
@@ -164,8 +123,8 @@ To have the `rbt` command line utility generate React code when running
 `rbt generate`, add the `--react` flag to `.rbtrc`. For example:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/.rbtrc&&lines=33-33) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/.rbtrc -->
+(CODE:src=../../../reboot/examples/chat-room/.rbtrc&&lines=33-33) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/.rbtrc -->
 
 ```
 generate --react=frontend/api
@@ -189,8 +148,8 @@ context is provided by a `RebootClientProvider`. It takes a
 generated React code will use to connect to the Reboot backend.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/counter/frontend/web-vite/src/main.tsx&&lines=8-10) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/counter/frontend/web-vite/src/main.tsx -->
+(CODE:src=../../../reboot/examples/counter/frontend/web-vite/src/main.tsx&&lines=8-10) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/counter/frontend/web-vite/src/main.tsx -->
 
 ```tsx
 <RebootClientProvider url={"http://localhost:9991"}>
@@ -204,8 +163,11 @@ All generated Reboot React Custom Hooks can now be used inside `<App />` or
 any of `App`'s children.
 
 :::tip
-Use a TLS endpoint to take advantage of HTTP/2
-multiplexing, a requirement for any Reboot React app with more than ~100 outstanding RPC calls, e.g., reactive readers or mutations.
+Use a TLS endpoint so the browser can use HTTP/2. Over plain HTTP,
+every reactive reader holds its own WebSocket, and browsers allow
+only around 200 of those per page (255 in Chrome). See
+[the `rbt` CLI](/rbt_cli#bring-your-own-certificate-with-rbt-dev-run)
+for local certificates.
 :::
 
 In practice, it is best to use an environment variable for your API endpoint.
@@ -213,8 +175,8 @@ In practice, it is best to use an environment variable for your API endpoint.
 For example:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/frontend/web/src/index.tsx&&lines=11-12) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/frontend/web/src/index.tsx -->
+(CODE:src=../../../reboot/examples/chat-room/frontend/web/src/index.tsx&&lines=11-12) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/frontend/web/src/index.tsx -->
 
 ```tsx
 (import.meta.env.VITE_REBOOT_URL as string) || "http://localhost:9991";
@@ -229,19 +191,41 @@ framework or library you use.
 Reboot generates TypeScript code. [Learn how to use Reboot in a vanilla JS environment.](#vanilla-javascript)
 :::
 
-## AI Chat App context
+## Signing users in
+
+When your application configures [`oauth=`](/users/oauth), three more
+hooks come into play:
+
+- `useSignIn()` and `useSignOut()` from `@reboot-dev/reboot-react`.
+- The generated `use<User>()` hook for your
+  [`User` type](/users/overview), which resolves the signed-in user
+  with no ID passed.
+
+```tsx
+const { user, isLoading } = useUser();
+const signIn = useSignIn();
+
+if (isLoading) return <p>Checking session…</p>;
+if (user === undefined) return <button onClick={() => signIn()}>Sign in</button>;
+```
+
+See [Web apps](/surfaces/web#signing-in) for the browser flow, and
+[React Native apps](/surfaces/react_native) for the native one.
+
+## In AI chat UIs
 
-When building [AI Chat Apps](/ai_chat_apps/get_started), the same
-generated React hooks work in both AI chat and browser contexts.
-The key differences:
+The same generated hooks work unchanged inside an
+[AI chat client](/surfaces/ai_chat), where a
+[`UI` method](/surfaces/ui_methods) renders your component. A few
+things differ:
 
 - **No `url` prop needed.** In the AI chat context,
   `RebootClientProvider` automatically detects the environment.
   You do not pass a `url`:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/main.tsx&lines=9-11) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/main.tsx -->
+(CODE:src=../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/main.tsx&lines=9-11) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/main.tsx -->
 
 ```tsx
 <RebootClientProvider>
@@ -258,12 +242,12 @@ The key differences:
   an `id`, the hook returns `{ counter, isLoading }`, where
   `counter` is `undefined` until the ID resolves, so check both
   before using the handle (see
-  [`UI` methods](/learn_more/implement/ui_methods) for a complete
+  [`UI` methods](/surfaces/ui_methods) for a complete
   component):
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.tsx&lines=10-31) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.tsx -->
+(CODE:src=../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.tsx&lines=10-31) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/mcp/clicker/App.tsx -->
 
 ```tsx
 export const ClickerApp: FC = () => {
@@ -301,8 +285,8 @@ const Clicker: FC<{ counter: UseCounterApi }> = ({ counter }) => {
   as props:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/ai-chat-counter-dashboard/frontend/mcp/dashboard/App.tsx&lines=20-21) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter-dashboard/frontend/mcp/dashboard/App.tsx -->
+(CODE:src=../../../reboot/examples/ai-chat-counter-dashboard/frontend/mcp/dashboard/App.tsx&lines=20-21) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter-dashboard/frontend/mcp/dashboard/App.tsx -->
 
 ```tsx
 export const DashboardApp: FC<DashboardConfig> = ({ personalizedMessage }) => {
@@ -319,8 +303,8 @@ export const DashboardApp: FC<DashboardConfig> = ({ personalizedMessage }) => {
 You can call a `reader` _reactively_ very simply:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=33-34) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
+(CODE:src=../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=33-34) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
 
 ```tsx
 const { useMessages, send } = useChatRoom({ id: STATE_MACHINE_ID });
@@ -334,7 +318,7 @@ Let's break this down.
 `useChatRoom` is a generated React custom hook that provides access to all of the methods
 defined on the `ChatRoom` state data type. The `id` that is passed is the ID that uniquely identifies your state.
 
-For every [`reader`](/learn_more/define/methods#kinds) method, a
+For every [`reader`](/define/methods#kinds) method, a
 React custom hook is generated, e.g., `useMessages`. Any time the `ChatRoom` state
 with the given `id` changes, `response` is updated and the component re-renders.
 
@@ -343,13 +327,13 @@ In this specific case, `useMessages` can be called with no arguments because
 
 ## Mutating state
 
-Mutators such as [`writer`](/learn_more/define/methods#kinds)
-and [`transaction`](/learn_more/define/methods#kinds) methods
+Mutators such as [`writer`](/define/methods#kinds)
+and [`transaction`](/define/methods#kinds) methods
 are both callable from React.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=33-33) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
+(CODE:src=../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=33-33) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
 
 ```tsx
 const { useMessages, send } = useChatRoom({ id: STATE_MACHINE_ID });
@@ -361,12 +345,12 @@ Reboot methods are accessed by their name in lower camel case, e.g.,
 `deleteAllMessages`.
 
 This line calls the
-[`writer`](/learn_more/define/methods#kinds) method, declared
-in the `.proto` as `Send`, using the lower camel case name `send`:
+[`writer`](/define/methods#kinds) method declared as `send` in the API
+definition, using its lower camel case name:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=37-37) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
+(CODE:src=../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=37-37) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
 
 ```tsx
 const { aborted } = await send({ message: message });
@@ -386,8 +370,8 @@ Reboot attaches all in-flight mutations to a `.pending` property of every mutato
 facilitate this, for example:
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=81-83) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
+(CODE:src=../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=81-83) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
 
 ```tsx
 {send.pending.map(({ request: { message }, isLoading }) => (
@@ -415,11 +399,11 @@ data races!
 
 Every call to a mutator returns both a `response` and an `aborted`; successful calls will ensure `aborted` is `undefined`.
 
-[Learn more about Reboot errors and error types.](/learn_more/errors)
+[Learn more about Reboot errors and error types.](/errors)
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=37-41) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
+(CODE:src=../../../reboot/examples/chat-room/frontend/web/src/App.tsx&&lines=37-41) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/frontend/web/src/App.tsx -->
 
 ```tsx
 const { aborted } = await send({ message: message });
@@ -431,8 +415,8 @@ if (aborted !== undefined) {
 
 <!-- MARKDOWN-AUTO-DOCS:END -->
 
-In this case, because the `Send` method in `chat_room.proto` does not define any
-specific error types, the only error that can be returned in the `aborted`
+In this case, because the `send` method does not define any specific
+error types, the only error that can be returned in the `aborted`
 object will be Reboot system errors such as `StateAlreadyConstructed`.
 
 :::info
@@ -503,16 +487,16 @@ To see the complete example, check out the [Reboot Counter example repo](https:/
 On the server, the code that is typically generated for TypeScript
 backends can be used to fetch initial data. In this case, we call
 `.count()`, a non-reactive, unary
-[`reader`](/learn_more/define/methods#kinds) method, to supply
+[`reader`](/define/methods#kinds) method, to supply
 the initial value.
 
 Importantly, we also need to construct an
-[`ExternalContext`](/learn_more/call/from_outside_your_app) to make
+[`ExternalContext`](/call/from_outside_your_app) to make
 this call safely.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/counter/frontend/web-next/app/page.tsx&&lines=6-19) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/counter/frontend/web-next/app/page.tsx -->
+(CODE:src=../../../reboot/examples/counter/frontend/web-next/app/page.tsx&&lines=6-19) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/counter/frontend/web-next/app/page.tsx -->
 
 ```tsx
 export default async function Home() {
@@ -540,8 +524,8 @@ The client-side call is completed as normal, but the data can be rendered immedi
 because it is passed into the component as a prop.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx&&lines=5-10) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx -->
+(CODE:src=../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx&&lines=5-10) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx -->
 
 ```tsx
 const TakeableCounter: React.FC<{ id: string; initialCount: number }> = ({
@@ -558,8 +542,8 @@ Now it is easy to render either the `initialCount` that was passed in initially
 current reactive value of the `response.count` object.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx&&lines=14-14) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx -->
+(CODE:src=../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx&&lines=14-14) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/counter/frontend/web-next/app/TakeableCounter.tsx -->
 
 ```tsx
 count={response ? response.count : initialCount}
diff --git a/documentation/docs/learn_more/call/from_within_your_app.mdx b/documentation/docs/call/from_within_your_app.mdx
similarity index 86%
rename from documentation/docs/learn_more/call/from_within_your_app.mdx
rename to documentation/docs/call/from_within_your_app.mdx
index 5bc9da7af..89570443f 100644
--- a/documentation/docs/learn_more/call/from_within_your_app.mdx
+++ b/documentation/docs/call/from_within_your_app.mdx
@@ -5,19 +5,19 @@ import TabItem from "@theme/TabItem";
 
 By "internal" to a Reboot application, we specifically mean within one
 of the methods that you've implemented for your
-[servicers](/learn_more/implement/servicers). Each of those
+[servicers](/implement/servicers). Each of those
 methods takes a `context` argument that you can use to make calls:
 
 <!-- TODO: add links to generated API documentation for these types. -->
 
-- `ReaderContext` - Passed to a [`reader`](/learn_more/define/methods#kinds).
-- `WriterContext` - Passed to a [`writer`](/learn_more/define/methods#kinds).
-- `TransactionContext` - Passed to a [`transaction`](/learn_more/define/methods#kinds).
-- `WorkflowContext` - Passed to a [`workflow`](/learn_more/implement/workflows).
+- `ReaderContext` - Passed to a [`reader`](/define/methods#kinds).
+- `WriterContext` - Passed to a [`writer`](/define/methods#kinds).
+- `TransactionContext` - Passed to a [`transaction`](/define/methods#kinds).
+- `WorkflowContext` - Passed to a [`workflow`](/implement/workflows).
 
 The types of these contexts allow Reboot (as well as static type
 checkers like `mypy`, `Pyright`, or `tsc`) to enforce its [safety
-guarantees](/learn_more/define/methods) throughout the call
+guarantees](/define/methods) throughout the call
 graph.
 
 ## Making calls to other durable data types
@@ -29,8 +29,8 @@ the method while passing along the `context` from your servicer method:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-pydantic/backend/src/bank_servicer.py&lines=56-65) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-pydantic/backend/src/bank_servicer.py -->
+(CODE:src=../../../reboot/examples/bank-pydantic/backend/src/bank_servicer.py&lines=56-65) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-pydantic/backend/src/bank_servicer.py -->
 
 ```py
 async def transfer(
@@ -49,8 +49,8 @@ async def transfer(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=46-54) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
+(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=46-54) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
 
 ```ts
 async transfer(
@@ -79,13 +79,13 @@ passed as a parameter to your method.
 `workflow` methods are an exception: they don't get direct access to
 `state`, but instead read snapshots of it and modify it explicitly
 via `write()` — see
-[Workflows](/learn_more/implement/workflows#reading-state).
+[Workflows](/implement/workflows#reading-state).
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/backend/src/chat_room_servicer.py&lines=24-32) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/backend/src/chat_room_servicer.py -->
+(CODE:src=../../../reboot/examples/chat-room/backend/src/chat_room_servicer.py&lines=24-32) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/backend/src/chat_room_servicer.py -->
 
 ```py
 async def send(
@@ -102,8 +102,8 @@ async def send(
   </TabItem>
   <TabItem value="typescript-class" label="TypeScript Class">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room-nodejs/backend/src/chat_room_servicer.ts&lines=16-22) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room-nodejs/backend/src/chat_room_servicer.ts -->
+(CODE:src=../../../reboot/examples/chat-room-nodejs/backend/src/chat_room_servicer.ts&lines=16-22) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room-nodejs/backend/src/chat_room_servicer.ts -->
 
 ```ts
 async send(
@@ -185,8 +185,8 @@ balances = await asyncio.gather(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/nodejs/yarn_zod_test/backend/src/bank.ts&lines=52-59) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/nodejs/yarn_zod_test/backend/src/bank.ts -->
+(CODE:src=../../../tests/reboot/nodejs/yarn_zod_test/backend/src/bank.ts&lines=52-59) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/nodejs/yarn_zod_test/backend/src/bank.ts -->
 
 ```ts
 return {
@@ -389,7 +389,7 @@ directly**. This is by design to prevent
 unsafe, partial updates in the case that one of the calls fails.
 
 If you need to call multiple writer methods atomically, use a
-[`transaction`](/learn_more/define/methods#kinds) method instead.
+[`transaction`](/define/methods#kinds) method instead.
 
 #### Scheduling writers from writers
 
@@ -400,8 +400,8 @@ later:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-pydantic/backend/src/account_servicer.py&lines=38-45) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-pydantic/backend/src/account_servicer.py -->
+(CODE:src=../../../reboot/examples/bank-pydantic/backend/src/account_servicer.py&lines=38-45) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-pydantic/backend/src/account_servicer.py -->
 
 ```py
 async def open(
@@ -418,8 +418,8 @@ async def open(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts&lines=11-24) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts -->
+(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts&lines=11-24) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts -->
 
 ```ts
 async open(
@@ -444,4 +444,4 @@ async open(
 
 This works because `.schedule()` creates a separate task that will
 execute independently, not as part of the current writer's execution.
-See [Tasks](/learn_more/tasks) for more details.
+See [Tasks](/tasks) for more details.
diff --git a/documentation/docs/learn_more/call/overview.mdx b/documentation/docs/call/overview.mdx
similarity index 79%
rename from documentation/docs/learn_more/call/overview.mdx
rename to documentation/docs/call/overview.mdx
index fddeb24be..71b5fd4b2 100644
--- a/documentation/docs/learn_more/call/overview.mdx
+++ b/documentation/docs/call/overview.mdx
@@ -4,7 +4,7 @@ import TabItem from "@theme/TabItem";
 # Overview
 
 Usually you'll call methods via the generated Python, TypeScript, or
-[React](/learn_more/call/from_react) client code (or libraries that
+[React](/call/from_react) client code (or libraries that
 wrap the generated code).
 
 In order to call a method on an instance of your data types you need
@@ -13,8 +13,8 @@ to first get a reference to it, e.g., on the backend via `ref()`:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&lines=50-50) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
+(CODE:src=../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&lines=50-50) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
 
 ```py
 from_account = Account.ref(request.from_account_id)
@@ -24,8 +24,8 @@ from_account = Account.ref(request.from_account_id)
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=50-50) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
+(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=50-50) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
 
 ```ts
 const fromAccount = Account.ref(request.fromAccountId);
@@ -46,7 +46,7 @@ const account = useAccount({ id });
 **You can think of a reference like a handle (and it's similar to a
 "stub" in gRPC), but getting a reference via `ref()` or `use...()`
 does not mean that an instance of the data type has been
-[constructed](/learn_more/call/overview#constructing-instances)!**
+[constructed](/call/overview#constructing-instances)!**
 
 In fact, the type returned from calling `.ref()` is a `WeakReference`,
 where "weak" indicates that the instance may or may not have been
@@ -82,8 +82,8 @@ avoid making the singleton a scalability bottleneck you should avoid
 storing too much data in a single instance of a data type.
 
 It's a good practice to ensure your singletons are constructed in the
-[`initialize`](/learn_more/applications#initialize-functions) function
-that you pass to [`Application`](/learn_more/applications).
+[`initialize`](/implement/application#initialize-functions) function
+that you pass to [`Application`](/implement/application).
 
 :::
 
@@ -91,14 +91,15 @@ that you pass to [`Application`](/learn_more/applications).
 ## Constructing instances
 
 You construct an instance of your data types either _implicitly_
-or _explicitly_, depending on whether or not you have explicitly
-designated certain methods as _constructors_ in your `.proto`, or as
-a _factory_ in your Pydantic or Zod schema.
+or _explicitly_, depending on whether or not you have designated a
+method as a _factory_ in your Pydantic or Zod schema.
 
 :::tip
-If your state can be default constructed, prefer _implicit_
-construction! Only use explicit construction if you have some
-_initialization that must be performed_.
+Prefer an explicit constructor for the types your application creates
+many of: it lets Reboot
+[generate the state ID](/concepts#let-reboot-generate-the-id) and
+gives you one place to initialize state. Implicit construction suits
+singletons and other instances whose ID you choose yourself.
 :::
 
 ### Implicit construction
@@ -142,15 +143,15 @@ once).
 If you've defined a constructor/factory for your data type then you
 must use it for constructing an instance.
 
-Here's an example, in both Zod and Pydantic, that designates
+Here's an example, in both Pydantic and Zod, that designates
 the `Open` method as an explicit constructor for `Account`:
 
 <!-- TODO: update this snippet to use the basic bank example once it lands. -->
 
 <Tabs groupId="language">
   <TabItem value="python" label="Pydantic" default>
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/bank-pydantic/api/bank/v1/account.py&syntax=python&lines=24-33) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-pydantic/api/bank/v1/account.py -->
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/bank-pydantic/api/bank/v1/account.py&syntax=python&lines=24-33) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-pydantic/api/bank/v1/account.py -->
 
 ```python
 AccountMethods = Methods(
@@ -230,8 +231,8 @@ an example of constructing an `Account` with an explicit ID using the
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&syntax=python&lines=34-38) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&syntax=python&lines=34-38) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
 
 ```python
 account, _ = await Account.open(
@@ -244,8 +245,8 @@ account, _ = await Account.open(
 <!-- MARKDOWN-AUTO-DOCS:END -->
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&syntax=typescript&lines=39-41) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&syntax=typescript&lines=39-41) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
 
 ```typescript
 const [account, response] = await Account.open(context, newAccountId, {
@@ -261,9 +262,9 @@ const [account, response] = await Account.open(context, newAccountId, {
 #### Idempotent construction
 
 You can call explicit constructors using
-[`idempotently()`](/learn_more/idempotency) external to a Reboot
+[`idempotently()`](/idempotency) external to a Reboot
 application (i.e., using an
-[`ExternalContext`](/learn_more/call/from_outside_your_app)):
+[`ExternalContext`](/call/from_outside_your_app)):
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
diff --git a/documentation/docs/learn_more/call/via_http.mdx b/documentation/docs/call/via_http.mdx
similarity index 92%
rename from documentation/docs/learn_more/call/via_http.mdx
rename to documentation/docs/call/via_http.mdx
index febd89bdc..5b91fdce0 100644
--- a/documentation/docs/learn_more/call/via_http.mdx
+++ b/documentation/docs/call/via_http.mdx
@@ -5,13 +5,13 @@ import TabItem from "@theme/TabItem";
 
 You can call into a Reboot application directly using HTTP in
 circumstances where you aren't using React or can't use an
-[`ExternalContext`](/learn_more/call/from_outside_your_app) because
+[`ExternalContext`](/call/from_outside_your_app) because
 Reboot doesn't generate code in the language you're using.
 
 :::tip
 
 If you're trying to call into a Reboot application using React, go
-[here](/learn_more/call/from_react)!
+[here](/call/from_react)!
 
 :::
 
diff --git a/documentation/docs/concepts.mdx b/documentation/docs/concepts.mdx
new file mode 100644
index 000000000..af7c07938
--- /dev/null
+++ b/documentation/docs/concepts.mdx
@@ -0,0 +1,256 @@
+# How Reboot works
+
+Most application stacks are assembled: a web framework, a database, an
+ORM, a cache, a queue, a session store, an auth provider, and a pile of
+glue holding them together. Every seam is somewhere a bug can hide, and
+every one of them is something you or your coding agent has to get
+right.
+
+Reboot replaces that assembly with one thing — a backend built out of
+**durable data structures** — and then constrains what you can do with
+them, so whole classes of bug are impossible by construction rather
+than merely discouraged. It is the same trade Rust's borrow checker
+makes for memory management and React makes for component-based
+frontends, applied to your backend.
+
+This page is the mental model. It is worth ten minutes before you write
+any code; everything else in these docs is a detail of something here.
+
+## Types, state, and methods
+
+A Reboot application is a set of **types**. A type has:
+
+- **State** — the data an instance of that type holds. Fields are
+  ordinary Python or TypeScript values, declared with
+  [Pydantic](/define/pydantic) in Python or
+  [Zod](/define/zod) in TypeScript.
+- **Methods** — the only way to read or change that state.
+
+That is the whole model. A `ChatRoom` holds messages and has a `send`
+method. An `Account` holds a balance and has `deposit` and `withdraw`.
+A `User` holds whatever you want to remember about a person.
+
+Reboot persists state for you. This is what a **durable application**
+means: the moment a function returns, its state is saved. If the
+process dies a millisecond later, the next one picks up exactly where
+it left off. You never write a query, open a transaction against a
+database, or think about connection pools.
+
+That is a step past a durable execution engine, which makes your
+*workflow* recoverable but leaves your data somewhere else. Here the
+application itself is durable, all the way down.
+
+## Instances and state IDs
+
+Each type has many **instances**, each identified by a **state ID** —
+a string that is unique within your application. Think of it as a
+primary key.
+
+### Let Reboot generate the ID
+
+Most of the time, don't choose the ID yourself. Give the type a
+constructor — a method declared with `factory=True` — and call it
+without an ID; Reboot mints a fresh, unique one for you:
+
+```python
+account, _ = await Account.open(context, customer_name="Ada")
+
+account.state_id  # The generated ID — hold on to this.
+```
+
+This is the recommended default, and it is what you should reach for
+unless you have a specific reason not to. A generated ID is unique by
+construction, so there is no "is this name already taken?" check to
+write, no collision between two users who both wanted `acme`, and
+nothing guessable for someone else to try.
+
+What you do with the ID is store it wherever the user will look it up
+from again — usually on their [`User`](/users/overview), which is the
+one instance the framework can always find.
+
+### When to write an ID yourself
+
+Two cases justify it:
+
+- **The ID already exists somewhere else.** `User` is the built-in
+  example: its state ID *is* the identity your auth provider issued,
+  which is exactly why Reboot can find a person's `User` without being
+  told who they are.
+- **There is genuinely only one.** A singleton — one `Bank`, one
+  site-wide `Leaderboard` — is easier to reach by a well-known ID than
+  to look up. Construct singletons in your application's
+  [`initialize`](/implement/application#initialize-functions)
+  function, and keep them small: everything in one instance is
+  everything that cannot be worked on in parallel.
+
+```python
+account = Account.ref("account-1234")
+```
+
+`ref()` gives you a handle, not a guarantee that the instance exists;
+see [Constructing instances](/call/overview#constructing-instances) for
+how instances come into being.
+
+### Why IDs matter beyond naming
+
+Reboot uses state IDs to partition your instances across CPU cores and
+machines. Two different `Account` instances never contend with each
+other, which is why a Reboot backend scales without you sharding
+anything by hand.
+
+## Method kinds
+
+Every method declares a [kind](/define/methods), and Reboot enforces
+what that kind is allowed to do:
+
+| Kind | What it may do |
+| --- | --- |
+| [`reader`](/implement/readers) | Read state, without changing any. A `reader` sees its own instance's state and can call other `reader` methods, so it can read across as many instances as it needs. Many readers run concurrently, and a reader can be subscribed to — which is what makes React clients reactive. |
+| [`writer`](/implement/writers) | Read and mutate its own instance's state, atomically; it can call `reader` methods to read others. Writers on an instance run one at a time. |
+| [`transaction`](/implement/transactions) | Read and mutate *several* instances atomically. Either all of it happens or none of it does. |
+| [`workflow`](/implement/workflows) | Run a long-lived, retryable process — minutes, days, or forever — without holding a lock. |
+| [`UI`](/surfaces/ui_methods) | Declare a React component an AI chat client can open. It has no backend implementation. |
+
+Kinds form a hierarchy: a method may only call methods with the same
+or stronger guarantees. A `reader` cannot call a `writer`, so a read
+can never sneak in a mutation. A `writer` cannot call another `writer`
+at all, so write atomicity is never quietly violated — reach for a
+`transaction` when you need to change several instances together.
+
+This is the trade Reboot asks you to make: you say a little more about
+each method up front, and in exchange the framework can guarantee
+correctness, run things in parallel safely, and recover from failures
+without your help. It is also what keeps the diff reviewable — a
+method's kind tells you what it can possibly do, whether a human or an
+agent wrote it.
+
+## Servicers: where you write the code
+
+An API definition declares *what* the methods are. A
+[servicer](/implement/servicers) implements them:
+
+```python
+class AccountServicer(Account.Servicer):
+
+    async def deposit(
+        self,
+        context: WriterContext,
+        request: Account.DepositRequest,
+    ) -> None:
+        self.state.balance += request.amount
+```
+
+`self.state` is the instance's state. Mutate it, and when the method
+returns successfully the new state is saved — all of your changes or,
+if the method fails, none of them. Nothing is written half-way.
+
+The `context` tells you who is calling (`context.auth`) and which
+instance you are in (`context.state_id`), and you pass it to every
+Reboot call you make from here, which is how those calls inherit this
+method's guarantees.
+
+## Users are the entry point
+
+Almost every application starts from "who is this?". Reboot builds
+that in.
+
+Declare a type named `User`, hand your `Application` an
+[`OAuth`](/users/oauth) configuration, and Reboot runs an OAuth server
+for you. When somebody signs in, Reboot **auto-constructs their
+`User`**: an instance whose state ID is that person's stable identity,
+created on first sign-in and found again on every sign-in after that.
+
+```python
+api = API(
+    User=Type(state=UserState, methods=UserMethods),
+    # ... your other types.
+)
+```
+
+You plug in your favorite auth provider — Google, GitHub, Auth0, Ory —
+and Reboot runs the flow in front of it, so you never write a session
+table or a "get or create user" helper. From the first line of your
+application code there is a `User` to hang everything else off: their
+documents, their orders, their chat rooms, their settings.
+
+`User` is also where per-user authorization comes from for free — by
+default a `User`'s methods are callable by that user and by your own
+application code, and by nobody else. See
+[Users and sign-in](/users/overview).
+
+## One backend, many frontends
+
+A Reboot backend does not care where a call comes from. One app serves
+every user — human or machine:
+
+- **Humans** reach it through a [web app](/surfaces/web), a
+  [React Native app](/surfaces/react_native), or an
+  [AI chat app](/surfaces/ai_chat), where
+  [`UI` methods](/surfaces/ui_methods) render React components inside
+  the conversation.
+- **Agents** reach it over [MCP](/surfaces/ai_chat), where the methods
+  you mark `mcp=Tool()` appear as tools.
+- **Services** reach it from
+  [your own backend code](/call/from_within_your_app), another
+  process, a script, or a
+  [plain HTTP request](/call/via_http).
+
+An agent can also run *inside* the app: see [Agents](/agents) for
+Pydantic AI agents whose model and tool calls are durable and
+replay-safe.
+
+Because identity is established by the backend rather than by any one
+client, a user who signs in on the web is the same user — the same
+`User` instance, the same state — in the mobile app and in the chat
+client.
+
+## Reactivity
+
+`reader` methods can be *subscribed to* rather than polled. A React
+component calls a generated hook, and Reboot pushes a new response
+every time the underlying state changes — whether the change came from
+that user, another user, a background workflow, or an AI calling a
+tool.
+
+```tsx
+const { useMessages, send } = useChatRoom({ id });
+const { response } = useMessages();
+```
+
+There is no cache to invalidate and no event bus to subscribe to. The
+read *is* the subscription. See
+[Call your API from React](/call/from_react).
+
+## When things take time, or fail
+
+Real applications wait: on a human, on a payment processor, on
+tomorrow. Reboot has durable primitives for each of these, so "the
+process restarted" is never a correctness problem:
+
+- [Tasks](/tasks) run work in the background, and can be scheduled for
+  later or on a recurring basis.
+- [Workflows](/implement/workflows) survive restarts: a failed
+  workflow is retried until it completes, and the steps that already
+  finished are memoized rather than run a second time.
+- [Side effects](/side_effects) wrap calls to the outside world in
+  `at_least_once` / `at_most_once` so a retry cannot double-charge
+  somebody.
+- [Idempotency](/idempotency) makes a retried mutation apply once, even
+  across clients and restarts.
+
+## What you still write yourself
+
+Reboot is not a no-code tool. You still design your types, write your
+business logic, and build your UI. What it takes off your plate is the
+infrastructure underneath: persistence, transactions, concurrency
+control, reactive fan-out, background execution, sign-in, and per-user
+authorization — the hard problems, solved once at the framework level,
+so neither you nor your coding agent ever has to solve them again.
+
+## Next
+
+- [Users and sign-in](/users/overview) — the entry point every app
+  starts from.
+- [Define your API](/define/overview) — declare your types.
+- [Build with Claude Code](/get_started/claude_code) — get a running
+  app in minutes.
diff --git a/documentation/docs/learn_more/define/methods.mdx b/documentation/docs/define/methods.mdx
similarity index 73%
rename from documentation/docs/learn_more/define/methods.mdx
rename to documentation/docs/define/methods.mdx
index a8d3e10e3..2f8d2e31b 100644
--- a/documentation/docs/learn_more/define/methods.mdx
+++ b/documentation/docs/define/methods.mdx
@@ -21,7 +21,7 @@ Enforcing these guarantees naturally creates a safety hierarchy, in which _**met
 ## Kinds
 
 <!-- TODO: Insert a callability diagram here.
-This is an existing flow chart about method kinds that we could use as a template: https://docs.google.com/presentation/d/10NpT5dixaa_DLYRtRajYr1heRNpoBkn6pPId0AmlAWw/edit#slide=id.g238161c3009_0_780 -->
+An existing flow chart about method kinds that could serve as a template: https://docs.google.com/presentation/d/10NpT5dixaa_DLYRtRajYr1heRNpoBkn6pPId0AmlAWw/edit#slide=id.g238161c3009_0_780 -->
 
 The five kinds of methods in Reboot are:
 
@@ -31,15 +31,19 @@ The five kinds of methods in Reboot are:
 | `writer` | `writer` methods can both read from and mutate state. `writer` execution happens serially on a given state, allowing each update to happen atomically. To enforce write atomicity, `writers` can call any `readers`, but they cannot call other `writers`. |
 | `transaction` | `transactions` combine multiple read/write operations into a single atomic action, often across multiple states. All of the reads and writes included in the `transaction` will happen atomically: once a state is involved in a `transaction`, no other RPCs may mutate its state until that `transaction` is complete. If any part of the `transaction` fails, the entire `transaction` will be rolled back. `transactions` may call `readers`, `writers`, and other `transactions`. |
 | `workflow` | `workflow` methods asynchronously combine multiple read/write operations _without_ holding a lock. State updates may be visible to the outside world before the `workflow` completes. If a failure occurs, the workflow is retried from the beginning until it runs to completion.|
-| `ui` | `ui` methods declare a React component to display in the AI chat interface. The React `App.tsx` is the implementation; there is no backend servicer code. When the AI calls the associated tool, the chat client opens the React app. See [UI methods](/learn_more/implement/ui_methods). |
-
-## Tool exposure
-
-When you define your API with
-[Pydantic](/learn_more/define/pydantic), every method must
-explicitly declare its MCP exposure with `mcp=Tool()` (to
-expose it as an AI-callable tool) or `mcp=None` (to hide it
-from the AI). This applies to all state types, including
-`User`. See
-[Creating tools](/learn_more/define/pydantic#creating-tools-for-the-ai)
-for details.
+| `UI` | `UI` methods declare a React component to display in the AI chat interface. The React `App.tsx` is the implementation; there is no backend servicer code. When the AI calls the associated tool, the chat client opens the React app. See [UI methods](/surfaces/ui_methods). |
+
+## Exposing methods to an AI
+
+Every method is callable from your own code, from a
+[web](/surfaces/web) or [React Native](/surfaces/react_native)
+frontend, and from anywhere else you have a client. Whether an **AI**
+may call it is a separate, explicit decision.
+
+When you define your API with [Pydantic](/define/pydantic), every
+method declares its MCP exposure with `mcp=Tool()` (expose it as an
+AI-callable tool) or `mcp=None` (hide it from the AI). There is no
+implicit default, so nothing reaches an AI by accident. This applies
+to all state types, including `User`. See
+[Creating tools](/define/pydantic#creating-tools-for-the-ai) and
+[AI chat apps](/surfaces/ai_chat).
diff --git a/documentation/docs/learn_more/define/overview.mdx b/documentation/docs/define/overview.mdx
similarity index 54%
rename from documentation/docs/learn_more/define/overview.mdx
rename to documentation/docs/define/overview.mdx
index d3316da6d..c56e5b80f 100644
--- a/documentation/docs/learn_more/define/overview.mdx
+++ b/documentation/docs/define/overview.mdx
@@ -9,9 +9,9 @@ define data types and methods on those data types that you can call.
 
 In Reboot, those data types are actually _durable state_, meaning that
 when you update them they get persisted for you. And the methods are
-of a specific [_kind_](/learn_more/define/methods), either a
+of a specific [_kind_](/define/methods), either a
 `reader`, `writer`, `transaction`, `workflow`, or
-[`ui`](/learn_more/implement/ui_methods).
+[`UI`](/surfaces/ui_methods).
 
 The combination of these data types and methods is called **durable
 data structures** (think durable objects, but so much more).
@@ -21,21 +21,27 @@ data structures** (think durable objects, but so much more).
 With Reboot, you define the API for your durable data structures up
 front:
 
-- [Define your API using Pydantic](/learn_more/define/pydantic) (Python — the only option for AI Chat Apps)
-- [Define your API using Zod](/learn_more/define/zod) (TypeScript only)
-- [Define your API using protobuf](/learn_more/define/protobuf) (TypeScript or Python — for full control)
+- [Define your API using Pydantic](/define/pydantic) — Python
+- [Define your API using Zod](/define/zod) — TypeScript
+
+### The `User` type
+
+One type name is special. A type named
+[`User`](/define/pydantic#special-state-user) is auto-constructed for
+each person who signs in, so it is where per-user state and per-user
+methods belong. See [Users and sign-in](/users/overview).
 
 ### Code generation
 
 Reboot generates:
 
 - Type-safe, language-specific code for:
-  - [Python and TypeScript servers](/learn_more/implement/servicers)
-  - [Python and TypeScript clients](/learn_more/call/from_within_your_app)
-  - [React](/learn_more/call/from_react)
-- AI chat tools (from
-  [`User`](/learn_more/define/pydantic#special-state-user) methods and
-  [`UI`](/learn_more/implement/ui_methods) annotations)
+  - [Python and TypeScript servers](/implement/servicers)
+  - [Python and TypeScript clients](/call/from_within_your_app)
+  - [React](/call/from_react), shared by web, React Native, and AI
+    chat frontends
+- AI chat tools, from methods marked `mcp=Tool()` and from
+  [`UI`](/surfaces/ui_methods) annotations
 
 :::note
 
diff --git a/documentation/docs/learn_more/define/pydantic.mdx b/documentation/docs/define/pydantic.mdx
similarity index 75%
rename from documentation/docs/learn_more/define/pydantic.mdx
rename to documentation/docs/define/pydantic.mdx
index 90e554b20..79f9fc830 100644
--- a/documentation/docs/learn_more/define/pydantic.mdx
+++ b/documentation/docs/define/pydantic.mdx
@@ -3,20 +3,114 @@ import TabItem from "@theme/TabItem";
 
 # Pydantic
 
-When building AI Chat Apps, your API is defined with
-[Pydantic](https://docs.pydantic.dev/). You can also use Pydantic
-for full-stack apps with Python backends.
+For Python backends, you define your API with
+[Pydantic](https://docs.pydantic.dev/). A Reboot API is centered on
+_types_, which contain _state_ and _methods_.
 
-## AI Chat App
+## A simple type
 
-A Reboot API is centered on _types_, which contain _state_ and
-_methods_. When building an AI Chat App, you define a `User`
-type (auto-constructed per authenticated user) whose methods
-create other state types. Methods with `mcp=Tool()` become
-[tools the AI can call](/learn_more/mcp_apps):
+Here is a `ChatRoom` with a `reader` and a `writer`:
 
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
+```python
+from typing import Optional
+from reboot.api import (
+    API,
+    Field,
+    Methods,
+    Reader,
+    Model,
+    Writer,
+    Type,
+)
+
+class ChatRoomState(Model):
+    messages: Optional[list[str]] = Field(tag=1)
+
+class MessagesResponse(Model):
+    messages: list[str] = Field(tag=1)
+
+class SendRequest(Model):
+    message: str = Field(tag=1)
+
+ChatRoomMethods = Methods(
+    messages=Reader(
+        request=None,
+        response=MessagesResponse,
+        description="Every message posted to the room so far.",
+        mcp=None,
+    ),
+    send=Writer(
+        request=SendRequest,
+        response=None,
+        description="Post one message to the room.",
+        mcp=None,
+    ),
+)
+
+api = API(
+    ChatRoom=Type(
+        state=ChatRoomState,
+        methods=ChatRoomMethods,
+    ),
+)
+```
+
+Reboot uses standard
+[Pydantic BaseModel](https://docs.pydantic.dev/latest/concepts/models/),
+with `Model` as the base class for your durable state types,
+request and response types.
+
+:::important
+All Pydantic fields must include a `tag` parameter using
+`Field(tag=N)`. This is required for safe backwards compatibility.
+:::
+
+:::important
+Every method must say whether an AI may call it: `mcp=Tool()` or
+`mcp=None`. There is no default, so leaving it off is an error. See
+[Creating tools for the AI](#creating-tools-for-the-ai).
+:::
+
+:::info Naming conventions
+Your state class should end in `State`, e.g., `UserState`,
+`CounterState`.
+:::
+
+## Special state: `User`
+
+Naming a type `User` in your `API(User=Type(...))` definition triggers
+special behavior:
+
+1. **Auto-construction**: a `User` instance is automatically created
+   for each person who signs in. You do not need an `initialize`
+   function or manual `create()` calls. Every field on `UserState`
+   must have a default value, or be optional, since instances are
+   created without arguments.
+2. **Automatic ID resolution**: callers never specify a state ID for
+   `User` methods — it is resolved from the authenticated user. That
+   is what lets `useUser()` in React, and an AI calling a tool, both
+   reach the right instance without being told who the user is.
+3. **Default authorization**: `User` methods are accessible to that
+   user and to app-internal calls. No `authorizer()` override is
+   needed. See
+   [Authorization](/users/authorization#defaults-you-get-for-free).
+
+`User` typically acts as an entry point: its methods create or look
+up other state types (like `Counter`) and return their IDs.
+
+Auto-construction needs to know who is signing in, so an application
+with a `User` type must configure
+[`Application(oauth=...)`](/users/oauth). See
+[Users and sign-in](/users/overview) for the whole picture.
+
+## A complete example
+
+`User` plus an application type, with a
+[`UI` method](/surfaces/ui_methods) and methods marked `mcp=Tool()`
+so an [AI chat client](/surfaces/ai_chat) can call them:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
 
 ```python
 # api/ai_chat_counter/v1/counter.py
@@ -150,45 +244,6 @@ api = API(
 
 <!-- MARKDOWN-AUTO-DOCS:END -->
 
-Reboot uses standard
-[Pydantic BaseModel](https://docs.pydantic.dev/latest/concepts/models/),
-with `Model` as the base class for your durable state types,
-request and response types.
-
-:::important
-All Pydantic fields must include a `tag` parameter using
-`Field(tag=N)`. This is required for safe backwards compatibility.
-:::
-
-:::info Naming conventions
-Your state class should end in `State`, e.g., `UserState`,
-`CounterState`.
-:::
-
-## Special state: `User`
-
-Naming a type `User` in your `API(User=Type(...))`
-definition triggers special behavior:
-
-1. **Auto-construction**: a `User` instance is automatically
-   created for each authenticated user. You do not need an
-   `initialize` function or manual `create()` calls. All fields
-   on `UserState` must have default values, since instances
-   are created without arguments.
-2. **Automatic ID resolution**: the AI never needs to specify a
-   state ID for `User` methods — it is resolved from the
-   authenticated user.
-3. **Default authorization**: `User` methods are accessible to
-   the owning user (whose `user_id` matches the state ID) and
-   to app-internal calls. No `authorizer()` override is needed.
-   See [Default authorizer](/learn_more/auth#default-authorizer)
-   for details.
-
-`User` typically acts as an entry point: its methods create or look
-up other state types (like `Counter`) and return their IDs. The AI
-tracks those IDs in its context window and passes them in subsequent
-tool calls.
-
 ## Creating tools for the AI
 
 ### Explicit `mcp=` on every method
@@ -289,59 +344,10 @@ Not every method should be an MCP tool:
 
 ## Method kinds
 
-Depending on its [kind](/learn_more/define/methods), a method
-might be able to only read (e.g., `Reader`) or both read and
-write (e.g., `Writer`) the state. A type can have any number of
-`Reader`, `Writer`, `Transaction`, `Workflow`, and
-[`UI`](/learn_more/implement/ui_methods) methods.
-
-## Full-stack
-
-You can also use Pydantic for full-stack apps that are not AI Chat Apps.
-In that case you do not need the `User` type, `UI` methods, or
-`description` fields:
-
-```python
-from typing import Optional
-from reboot.api import (
-    API,
-    Field,
-    Methods,
-    Reader,
-    Model,
-    Writer,
-    Type,
-)
-
-class ChatRoomState(Model):
-    messages: Optional[list[str]] = Field(tag=1)
-
-class MessagesResponse(Model):
-    messages: list[str] = Field(tag=1)
-
-class SendRequest(Model):
-    message: str = Field(tag=1)
-
-ChatRoomMethods = Methods(
-    messages=Reader(
-        request=None,
-        response=MessagesResponse,
-        description="Every message posted to the room so far.",
-    ),
-    send=Writer(
-        request=SendRequest,
-        response=None,
-        description="Post one message to the room.",
-    ),
-)
-
-api = API(
-    ChatRoom=Type(
-        state=ChatRoomState,
-        methods=ChatRoomMethods,
-    ),
-)
-```
+Depending on its [kind](/define/methods), a method might be able to
+only read (e.g., `Reader`) or both read and write (e.g., `Writer`) the
+state. A type can have any number of `Reader`, `Writer`,
+`Transaction`, `Workflow`, and [`UI`](/surfaces/ui_methods) methods.
 
-To learn more about how you implement each data type's methods
-see [Implement your API](/learn_more/implement/servicers).
+To learn more about how you implement each data type's methods see
+[Implement your API](/implement/servicers).
diff --git a/documentation/docs/learn_more/define/zod.mdx b/documentation/docs/define/zod.mdx
similarity index 91%
rename from documentation/docs/learn_more/define/zod.mdx
rename to documentation/docs/define/zod.mdx
index cb11d9df6..e1c6b0ae2 100644
--- a/documentation/docs/learn_more/define/zod.mdx
+++ b/documentation/docs/define/zod.mdx
@@ -48,7 +48,7 @@ All fields must include a `tag` in their `.meta()`, e.g.,
 compatibility.
 :::
 
-Depending on its [kind](/learn_more/define/methods), a method
+Depending on its [kind](/define/methods), a method
 might be able to only read (e.g., `reader`) or both read and write
 (e.g., `writer`) the state.
 
@@ -57,4 +57,4 @@ method, but it can have any number of `reader`, `writer`,
 `transaction`, and `workflow` methods.
 
 To learn more about how you implement each data type's methods see
-[Implement your API](/learn_more/implement/servicers).
+[Implement your API](/implement/servicers).
diff --git a/documentation/docs/deploy_on_reboot_cloud.md b/documentation/docs/deploy_on_reboot_cloud.md
index 9a1595edb..8d35fcbb1 100644
--- a/documentation/docs/deploy_on_reboot_cloud.md
+++ b/documentation/docs/deploy_on_reboot_cloud.md
@@ -62,6 +62,36 @@ You must have Docker installed locally to build the container.
 (`linux/amd64`) and pushes it to a registry managed by Reboot Cloud, so
 you don't need your own container registry.
 
+### Get your auth ready for production
+
+If your application signs users in — that is, if it configures
+[`oauth=`](/users/oauth) — three things need to be true before you
+deploy:
+
+1. **A real provider in the `prod` arm.** `Development()` must never
+   serve production traffic, and `prod=None` makes the deployment fail
+   to start on purpose. Pick a
+   [provider](/users/providers) and pass its credentials from
+   environment variables.
+2. **`allowed_origins` set explicitly.** List your web app's origin,
+   or pass `[]` for same-origin-only. Omitting it is a startup error
+   in production.
+3. **Reboot's callback URL registered** with your identity provider:
+   `https://<your-backend-url>/__/oauth/callback`.
+
+Deliver client IDs and secrets as [secrets](/secrets), never in
+source:
+
+```console
+$ rbt cloud secret set \
+    --application-name=my-app \
+    --organization=my-org \
+    GOOGLE_OAUTH_CLIENT_SECRET
+```
+
+Reboot Cloud provides the cryptographic root keys your application
+signs sessions with, so there is nothing to configure for that here.
+
 ## Deploy with `rbt cloud up`
 
 `rbt cloud up` builds your container, pushes it, and deploys it as a
@@ -143,7 +173,7 @@ tracked in [this issue](https://github.com/reboot-dev/reboot/issues/71).
 - `rbt cloud secret set`, `rbt cloud secret list`, and
   `rbt cloud secret delete` manage the secrets that your deployed
   application can read as environment variables. See
-  [Secrets](/learn_more/secrets) for details.
+  [Secrets](/secrets) for details.
 - `rbt cloud logs` streams the logs of your deployed application. Use
   `--follow` to keep following new log lines as they are produced, and
   `--revisions` to select which revisions to show logs for.
diff --git a/documentation/docs/deploy_on_your_own.md b/documentation/docs/deploy_on_your_own.md
index ac2fea161..a88a8968f 100644
--- a/documentation/docs/deploy_on_your_own.md
+++ b/documentation/docs/deploy_on_your_own.md
@@ -49,6 +49,18 @@ serve run --application-name=my-app
 serve run --tls=external
 ```
 
+### Environment
+
+Two environment variables matter beyond the flags above:
+
+| Variable | Why |
+| --- | --- |
+| `REBOOT_CRYPTO_ROOT_KEYS` | Required. Reboot derives keys from it — the one your [OAuth server](/users/oauth) signs session tokens with, the one [`Ciphertext`](/library_services/ciphertext) encrypts with. Every server process of one application must be given the *same* value, and it must outlive the state it protects. `rbt dev run` and Reboot Cloud set it for you; `rbt serve` does not. |
+| `PORT` (or `RBT_PORT`) | An alternative to `--port`, which many hosting platforms set automatically. |
+
+Your identity provider's client ID and secret belong in the
+environment too; see [Secrets](/secrets).
+
 ### Kubernetes
 The recommended deployment model for `rbt serve` on Kubernetes is to store Reboot's state in
 either:
diff --git a/documentation/docs/deploy_operate/import_export.md b/documentation/docs/deploy_operate/import_export.md
index 95d43e4b1..2eaf44657 100644
--- a/documentation/docs/deploy_operate/import_export.md
+++ b/documentation/docs/deploy_operate/import_export.md
@@ -14,7 +14,7 @@ Data is exported as one [JSON lines file](https://jsonlines.org/) per database,
 
 The types of exported data are:
 * The state for each of your data type instances themselves - _Useful for interoperating with OLAP systems._
-* All [tasks](/learn_more/tasks) executed on behalf of states - _Useful for backups: if you have other use cases for exported tasks, [please let us know!](https://discord.com/invite/cRbdcS94Nr)_
+* All [tasks](/tasks) executed on behalf of states - _Useful for backups: if you have other use cases for exported tasks, [please let us know!](https://discord.com/invite/cRbdcS94Nr)_
 * Idempotent mutations - _Useful for backups._
 
 When importing data, any number of files are accepted and automatically partitioned
diff --git a/documentation/docs/develop_locally.md b/documentation/docs/develop_locally.md
index 047e9b32c..1ab552b1a 100644
--- a/documentation/docs/develop_locally.md
+++ b/documentation/docs/develop_locally.md
@@ -6,8 +6,12 @@ import TabItem from "@theme/TabItem";
 This page provides an overview of getting your development environment
 ready for building Reboot applications. Once your development
 environment is ready you can then start to
-[define](/learn_more/define/overview) and
-[implement](/learn_more/implement/servicers) your API.
+[define](/define/overview) and
+[implement](/implement/servicers) your API.
+
+New to Reboot? [Build with Claude Code](/get_started/claude_code) or
+[Codex](/get_started/codex) gets you a running app in minutes; this
+page is the reference behind what they set up.
 
 ## Set up your environment
 
@@ -77,12 +81,19 @@ them correctly to `rbt`.
 
 Here is a suggested file layout:
 
-| Files    | Directory |
+| Files | Directory |
 | -------- | ------- |
-| `*.proto`  | `api/`    |
+| API definitions (`*.py`, `*.ts`) | `api/` |
 | Backend source `*.py`, `*.ts/js` | `backend/src` |
 | Backend tests `*.py`, `*.ts/js` | `backend/tests` |
-| Frontend | `web` |
+| Generated React client | `frontend/api` |
+| Browser app | `frontend/web` |
+| React Native app | `frontend/mobile` |
+| `UI` method apps, one per method | `frontend/mcp/<name>` |
+
+Putting the generated client in `frontend/api` lets every frontend of
+your application share one copy of it. See
+[One backend, many frontends](/surfaces/overview).
 
 ## `.rbtrc` and flags
 
@@ -171,30 +182,32 @@ rbt generate --python=backend/api/ api/ -- --mypy_out=backend/api/
 In `.rbtrc`:
 
 ```shell
-# Find '.proto' files in 'api/'.
+# Find API definitions in 'api/'.
 generate api/
 
-# Generate 'python' code from our '.proto' files in 'backend/api/'.
+# Generate Python code into 'backend/api/'.
 generate --python=backend/api/
 
-# Generate 'mypy' code from our '.proto' files in 'backend/api/mypy/'.
+# Generate 'mypy' stubs into 'backend/api/mypy/'.
 generate -- --mypy_out=backend/api/mypy/
 ```
 
-In these examples, the order of the flags is crucial. All flags that appear
-after `--` are passed directly to the underlying tool (in this case,
-`protoc`).
+In these examples, the order of the flags is crucial. All flags that
+appear after `--` are passed directly to the underlying code
+generator.
 
-#### AI Chat App flags
+#### Frontend flags
 
-When building [AI Chat Apps](/ai_chat_apps/get_started), add these
-to your `.rbtrc`:
+When your application has a React frontend — a
+[web app](/surfaces/web), a
+[React Native app](/surfaces/react_native), or
+[`UI` methods](/surfaces/ui_methods) — add these to your `.rbtrc`:
 
 ```shell
-# Generate React hooks for AI Chat App UIs.
+# Generate typed React hooks, shared by every frontend.
 generate --react=frontend/api
 
-# Proxy UIs through Vite for hot module replacement.
+# Proxy the frontend through Vite for hot module replacement.
 dev run --frontend-root-path=frontend
 
 dev run:hmr --frontend-host=http://localhost:4444
@@ -213,8 +226,8 @@ dev run --default-config=hmr
 
 <!-- ## Boilerplate code
 
-The `rbt generate` command can generate boilerplate code based on your `.proto`
-files, giving you copy-paste-able Python/TypeScript method definitions for which
+The `rbt generate` command can generate boilerplate code based on your API
+definitions, giving you copy-paste-able Python/TypeScript method definitions for which
 you only need to fill in the implementation. To generate the boilerplate code,
 use the `--boilerplate` flag followed by the path to the directory where you
 want the boilerplate code to be placed:
@@ -266,9 +279,9 @@ By default your application state will not be persisted across
 restarts. To persist state, you can pass an `--application-name=...` flag to `rbt dev
 run`.
 
-When state is persisted, backwards incompatible changes in your `.proto` files
-are detected, and will trigger errors to encourage resolving them before they
-reach production. The `--on-backwards-incompatibility` flag allows you to control
+When state is persisted, backwards incompatible changes to your API
+definitions are detected, and will trigger errors to encourage
+resolving them before they reach production. The `--on-backwards-incompatibility` flag allows you to control
 what happens when backwards incompatibility is encountered:
 
 * `ask`: (default) Asks whether you would like to expunge the stored state to
diff --git a/documentation/docs/learn_more/errors.mdx b/documentation/docs/errors.mdx
similarity index 72%
rename from documentation/docs/learn_more/errors.mdx
rename to documentation/docs/errors.mdx
index be449f0c2..06a5891db 100644
--- a/documentation/docs/learn_more/errors.mdx
+++ b/documentation/docs/errors.mdx
@@ -31,9 +31,8 @@ Throwing any unexpected error can then be treated as a bug to be reported (class
 
 Reboot methods should enumerate all errors that are expected as part of normal
 business in their API definitions — whether you [define your
-API](/learn_more/define/overview) with
-[Pydantic](/learn_more/define/pydantic), [Zod](/learn_more/define/zod), or
-[protobuf](/learn_more/define/protobuf).
+API](/define/overview) with [Pydantic](/define/pydantic) or
+[Zod](/define/zod).
 
 For example, a `Withdraw` method for a bank account might raise an
 `OverdraftError` if the account doesn't have sufficient funds for the requested
@@ -43,8 +42,8 @@ method's `errors`:
 <Tabs groupId="language">
   <TabItem value="python" label="Pydantic" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../tests/reboot/documentation/errors_pydantic.py&lines=1-24) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/errors_pydantic.py -->
+(CODE:src=../../tests/reboot/documentation/errors_pydantic.py&lines=1-24) -->
+<!-- The below code snippet is automatically added from ../../tests/reboot/documentation/errors_pydantic.py -->
 
 ```py
 from reboot.api import Field, Methods, Model, Writer
@@ -77,8 +76,8 @@ AccountMethods = Methods(
   </TabItem>
   <TabItem value="typescript" label="Zod">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../tests/reboot/documentation/errors_zod.ts&lines=1-27) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/errors_zod.ts -->
+(CODE:src=../../tests/reboot/documentation/errors_zod.ts&lines=1-27) -->
+<!-- The below code snippet is automatically added from ../../tests/reboot/documentation/errors_zod.ts -->
 
 ```ts
 import { writer } from "@reboot-dev/reboot-api";
@@ -110,38 +109,6 @@ export const Account = {
 };
 ```
 
-<!-- MARKDOWN-AUTO-DOCS:END -->
-  </TabItem>
-  <TabItem value="proto" label="Proto">
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/api/bank/v1/account.proto&syntax=protobuf&lines=37-42) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/api/bank/v1/account.proto -->
-
-```protobuf
-rpc Withdraw(WithdrawRequest) returns (WithdrawResponse) {
-  option (rbt.v1alpha1.method) = {
-    writer: {},
-    errors: [ "OverdraftError" ],
-  };
-}
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-These errors are themselves defined by proto messages.
-
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/api/bank/v1/errors.proto&syntax=protobuf&lines=12-16) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/api/bank/v1/errors.proto -->
-
-```protobuf
-// Error returned when a withdrawal would overdraft the account.
-message OverdraftError {
-  // Amount that we would have overdraft by.
-  uint32 amount = 1;
-}
-```
-
 <!-- MARKDOWN-AUTO-DOCS:END -->
   </TabItem>
 </Tabs>
@@ -160,8 +127,8 @@ error types is incomplete or gets updated.
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/bank/backend/src/account_servicer.py&lines=57-68) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/src/account_servicer.py -->
+(CODE:src=../../reboot/examples/monorepo/bank/backend/src/account_servicer.py&lines=57-68) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/monorepo/bank/backend/src/account_servicer.py -->
 
 ```py
 async def withdraw(
@@ -182,8 +149,8 @@ async def withdraw(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts&lines=42-58) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts -->
+(CODE:src=../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts&lines=42-58) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts -->
 
 ```ts
 async withdraw(
@@ -216,8 +183,8 @@ Here's an example of how the `OverdraftError` can be caught in a type-safe way:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py&lines=51-61) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py -->
+(CODE:src=../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py&lines=51-61) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py -->
 
 ```py
 try:
@@ -237,8 +204,8 @@ except Account.WithdrawAborted as aborted:
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/bank-nodejs/backend/tests/test.ts&lines=21-34) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/tests/test.ts -->
+(CODE:src=../../reboot/examples/bank-nodejs/backend/tests/test.ts&lines=21-34) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/bank-nodejs/backend/tests/test.ts -->
 
 ```ts
 try {
diff --git a/documentation/docs/full_stack_apps/examples.md b/documentation/docs/full_stack_apps/examples.md
deleted file mode 100644
index ce7eba91e..000000000
--- a/documentation/docs/full_stack_apps/examples.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# Examples
-
-Full-stack Reboot application examples with React frontends.
-Looking for AI Chat App examples? See
-[AI Chat App Examples](/ai_chat_apps/examples).
-
-## `prosemirror-zod`
-
-[`reboot-dev/reboot-prosemirror-zod`](https://github.com/reboot-dev/reboot-prosemirror-zod) - _TypeScript backend, React frontend_
-
-This example demonstrates integration with the popular
-[ProseMirror](https://prosemirror.net) library.
-
-It demonstrates:
-
-* how to _sync_ between a React frontend and a Reboot backend
-* how to run a long-lived control loop using a [`workflow`](/learn_more/define/methods#kinds) method, which takes checkpoints of the ProseMirror document
-
-## `bank-zod`
-
-[`reboot-dev/reboot-bank-zod`](https://github.com/reboot-dev/reboot-bank-zod) - _TypeScript backend, React frontend_
-
-The `bank-zod` example demonstrates a multi-user "bank", with signup,
-transfers, and interest calculations. It strikes a good balance between simplicity and
-real-world utility.
-
-It demonstrates:
-* a debit/credit transaction that atomically moves funds between users (the canonical transaction example!)
-* different [data types](/learn_more/define/overview) on the backend
-* a task to give users interest
-* a reactive frontend
-
-## `bank-pydantic`
-
-[`reboot-dev/reboot-bank-pydantic`](https://github.com/reboot-dev/reboot-bank-pydantic) - _Python backend, React frontend_
-
-The `bank-pydantic` example demonstrates a multi-user "bank", with signup,
-transfers, and interest calculations. It strikes a good balance between simplicity and
-real-world utility.
-
-It demonstrates:
-* a debit/credit transaction that atomically moves funds between users (the canonical transaction example!)
-* different [data types](/learn_more/define/overview) on the backend
-* a task to give users interest
-* a reactive frontend
-<!-- TODO: Deep link to the task, transaction, and mailgun integration. #3515. -->
-
-## `bank`
-
-[`reboot-dev/reboot-bank`](https://github.com/reboot-dev/reboot-bank) - _Python backend, React frontend_
-
-The `bank` example demonstrates a multi-user "bank", with signup,
-transfers, and interest calculations. It strikes a good balance between simplicity and
-real-world utility.
-
-It demonstrates:
-* a debit/credit transaction that atomically moves funds between users (the canonical transaction example!)
-* different [data types](/learn_more/define/overview) on the backend
-* use of the [Mailgun integration](/library_services/mailgun) to send an email (transactionally!) as part of
-  user signup
-* a task to give users interest
-* a reactive frontend
-<!-- TODO: Deep link to the task, transaction, and mailgun integration. #3515. -->
-
-## `counter`
-
-[reboot-dev/reboot-counter](https://github.com/reboot-dev/reboot-counter) - _TypeScript backend, React frontend_
-
-The `counter` example is our most concise demonstration
-of a Reboot transaction and reactive frontend.
-
-It includes:
-* a reactive frontend
-* multiple instances of the same [data type](/learn_more/define/overview)
-* a simple [transaction](/learn_more/define/methods#kinds) that
-  [atomically moves counts between counters](https://github.com/reboot-dev/reboot-counter/blob/ae017cbe980a1f1cbb6002c28828d333e26b7a64/backend/src/counter_servicer.ts#L36-L58)
-
-## `hello`
-
-[reboot-dev/reboot-hello](https://github.com/reboot-dev/reboot-hello) - _Python backend, React frontend_
-
-The [`hello` example](https://github.com/reboot-dev/reboot-hello) demonstrates
-the simplest possible chat app: a single user, and a [singleton](/learn_more/call/overview#state-ids)
-"chat room". It contains:
-* a reactive frontend: open two browsers pointed at the same backend and see messages flow!
-* [optimistic updates](/learn_more/call/from_react#optimistic-updates): sent messages are
-  [rendered as pending](https://github.com/reboot-dev/reboot-hello/blob/9f8bea8992c6b4a11fa16bd60429abc4d5adc42d/web/src/App.tsx#L75-L83)
-  until they have been reflected in state received from the backend.
-* a `Dockerfile` that shows
-  [how to publish a Reboot app to the Reboot Cloud](https://github.com/reboot-dev/reboot-hello?tab=readme-ov-file#running-on-the-reboot-cloud).
-
-Because of `hello`'s simplicity, it does not use any [transactions](/learn_more/define/methods#kinds) --
-see the [`bank`](#bank) or [`counter`](#counter) examples for those.
-
-
-## `boutique`
-
-[reboot-dev/reboot-boutique](https://github.com/reboot-dev/reboot-boutique) - _Python backend, React frontend_
-
-The [`boutique` example](https://github.com/reboot-dev/reboot-boutique) is our largest
-example. It demonstrates a fairly complete web-shop, factored out into many components which would
-likely be maintained by separate teams.
-
-It was originally forked from
-[GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo),
-and demonstrates how Reboot makes it simple to write correct microservice applications.
-
-Of particular note, it has:
-* a more complex React frontend
-* many different [data types](/learn_more/define/overview) and API interactions
-* a multi-faceted ["checkout" method](https://github.com/reboot-dev/reboot-boutique/blob/7480e9d6b0a72c560a54f73571c49b10d3fa5478/backend/src/checkout/servicer.py#L45-L149)
-  which transactionally composes method calls to many other services. Use of a transaction
-  is critical in this case, because if any of the methods involved in the transaction fail,
-  then the entire transaction is aborted, atomically
-* calls to Reboot-hosted gRPC services
-
-The boutique is our largest example, so consider visiting the [`hello`](#hello),
-[`counter`](#counter), or [`bank`](#bank) examples first to get your feet wet!
diff --git a/documentation/docs/full_stack_apps/get_started_claude_code.mdx b/documentation/docs/full_stack_apps/get_started_claude_code.mdx
deleted file mode 100644
index 4f25ae9d9..000000000
--- a/documentation/docs/full_stack_apps/get_started_claude_code.mdx
+++ /dev/null
@@ -1,209 +0,0 @@
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Get Started (with Claude Code)
-
-Build a full-stack app — a Reboot backend behind a standalone React
-frontend served at a normal URL — using
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
-and the Reboot plugin. Claude Code writes the code for you: you
-describe what you want, approve the plan, and it scaffolds the
-entire project.
-
-## Install the Reboot plugin
-
-The plugin bundles everything Reboot needs, so
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
-itself is the only thing you need to have installed.
-
-<Tabs groupId="install-method">
-  <TabItem value="quick" label="Quick install">
-
-Install the Reboot plugin for Claude Code with a single
-command:
-
-```sh
-curl -fsSL https://reboot.dev/install.sh | bash
-```
-
-This registers the Reboot marketplace, installs the plugin,
-and pre-installs its pinned dependencies so your first build
-runs without waiting on downloads.
-
-Then start Claude Code — or, if it was already running while you
-installed, restart it — so the plugin loads.
-
-  </TabItem>
-  <TabItem value="manual" label="Manual install">
-
-Add the marketplace and install the plugin yourself with
-Claude Code:
-
-```
-claude plugin marketplace add reboot-dev/reboot-plugin
-```
-
-```
-claude plugin install reboot@reboot-plugin
-```
-
-Or, to auto-enable the plugin for your whole team, add this to your
-project's `.claude/settings.json`:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "reboot-plugin": {
-      "source": {
-        "source": "github",
-        "repo": "reboot-dev/reboot-plugin"
-      }
-    }
-  },
-  "enabledPlugins": {
-    "reboot@reboot-plugin": true
-  }
-}
-```
-
-Restart any Claude Code session that was already running when you
-installed the Reboot plugin so the new plugin loads.
-
-  </TabItem>
-</Tabs>
-
-## Use the skill
-
-Once installed, invoke the skill with a description of your app:
-
-```
-/reboot:web-app Build a web app where users can sign up and keep a list of chat rooms
-```
-
-You can also just describe what you want to build in a normal
-prompt — Claude Code selects the right Reboot skill from your
-description, and saying "website", "web app", "SPA", "in the
-browser", or naming a URL is enough for it to pick the Web App
-builder. Or invoke `/reboot:app`, which asks whether you want an AI
-Chat App or a standalone Web App and then hands off to the matching
-skill — for this guide, pick the Web App.
-
-The skill settles the design before it writes any code. It will:
-
-1. Analyze your description and propose a state model
-2. Map out which types and methods your app needs, which pages the
-   frontend has, and how users sign in
-3. State that design back to you — so you can redirect it before
-   the code exists
-
-Claude Code then scaffolds the full project — API definition,
-backend servicers, React SPA, and configuration — builds it, writes
-and runs backend tests, and starts the app.
-
-:::info The agent-driven path builds a Python backend
-The skill scaffolds a Python backend with a React frontend. If you
-want a **TypeScript** backend, follow the hand-written
-[TypeScript guide](/full_stack_apps/typescript) instead — but note
-that TypeScript backend support is in alpha.
-:::
-
-## What gets created
-
-The skill generates a complete full-stack Reboot app. The most
-relevant files are:
-
-```
-my-app/
-├── .rbtrc                    # Reboot CLI config
-├── pyproject.toml            # Python deps (uv)
-├── api/
-│   └── my_app/v1/
-│       └── my_app.py         # API definition (Pydantic)
-├── backend/
-│   ├── api/                  # Generated Python bindings
-│   ├── src/
-│   │   ├── main.py           # Application entrypoint
-│   │   └── servicers/
-│   │       └── my_app.py     # Servicer implementation
-│   └── tests/
-│       └── my_app_test.py    # Backend behavior tests
-└── frontend/
-    ├── package.json
-    ├── build.mjs             # Discovers + builds every UI
-    ├── vite.config.ts        # Vite dev server + build config
-    ├── index.css             # Theme variables
-    ├── api/                  # Generated React bindings
-    └── web/                  # The standalone browser SPA
-        ├── index.html
-        ├── .env.development  # VITE_REBOOT_URL=http://localhost:9991
-        └── src/
-            ├── main.tsx      # RebootClientProvider entry
-            └── App.tsx       # Routes + top-level component
-```
-
-Each entity your app manages becomes its own
-[durable state type](/learn_more/define/overview) with its own
-methods; the frontend calls those methods through the typed
-[React hooks](/learn_more/call/from_react) that `rbt generate`
-emits into `frontend/api`. If your app has per-user state, the
-skill also declares a `User` type and signs browser users in
-through Reboot's [built-in OAuth support](/learn_more/auth) —
-`Development()` in development, so you can sign in as any
-identity without registering a provider first.
-
-## Test your app
-
-Claude Code writes backend unit tests covering your app's user
-stories and runs them before handing the app off — they help to
-make sure that your app works, and keeps working.
-
-Once the tests pass, Claude Code starts everything the app needs:
-
-* the Reboot backend (`rbt dev run`), which serves your API at
-  `http://localhost:9991`, and
-* the Vite dev server, on `http://localhost:4444`.
-
-It then hands you `http://localhost:4444`, which redirects to your
-web app. In development, click "Sign in" and pick (or make up) a
-`Development` identity; signing in auto-constructs your `User`.
-
-## Iterate on your app
-
-You can also use the skill to modify an existing app:
-
-```
-/reboot:web-app Add a page that shows the messages in a single chat room
-```
-
-The skill reads your current code, plans the changes, and waits
-for approval before editing.
-
-## Run it again later
-
-If you come back to your project in a new session, ask Claude Code
-to bring the app back up:
-
-```
-/reboot:run my-app
-```
-
-Or just say "Run this Reboot app" from the project directory. The
-run skill starts the backend and the frontend dev server and points
-you at the app.
-
-## Next steps
-
-* **[Get Started (with Codex)](/full_stack_apps/get_started_codex)** —
-  the equivalent agent-driven workflow for Codex.
-* **[Get Started (Python)](/full_stack_apps/python)** — build a
-  backend step by step to understand every file.
-* **[Build a React frontend](/full_stack_apps/react)** — the
-  hand-written version of the frontend the skill generates.
-* **[Call your API from React](/learn_more/call/from_react)** — the
-  full reference for the generated hooks.
-* **[Full-stack Examples](/full_stack_apps/examples)** — more
-  examples to explore.
-* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — deploy
-  your app with `rbt cloud up`.
-* **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** — ask
-  questions and share what you're building!
diff --git a/documentation/docs/full_stack_apps/get_started_codex.mdx b/documentation/docs/full_stack_apps/get_started_codex.mdx
deleted file mode 100644
index 1d3e21f8b..000000000
--- a/documentation/docs/full_stack_apps/get_started_codex.mdx
+++ /dev/null
@@ -1,232 +0,0 @@
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Get Started (with Codex)
-
-Build a full-stack app — a Reboot backend behind a standalone React
-frontend served at a normal URL — using
-[Codex](https://developers.openai.com/codex/) and the Reboot
-plugin. Codex writes the code for you: describe the app, approve
-the proposed design, and it scaffolds the Reboot backend, React
-frontend, tests, and local development setup.
-
-## Install the Reboot plugin
-
-The plugin bundles everything Reboot needs, so the only prerequisite is
-[Codex](https://developers.openai.com/codex/cli) itself (installed and
-authenticated).
-
-<Tabs groupId="install-method">
-  <TabItem value="quick" label="Quick install">
-
-Install the Reboot plugin for Codex with a single command:
-
-```sh
-curl -fsSL https://reboot.dev/install.sh | bash
-```
-
-The installer detects Codex, registers the Reboot plugin marketplace,
-installs the plugin, enables Codex hooks, and pre-installs the pinned
-tool shims used by the skill.
-
-:::warning Temporary Codex sandbox opt-out
-The installer currently asks to disable Codex's sandbox globally by
-writing `sandbox_mode = "danger-full-access"` into
-`~/.codex/config.toml`. This is a temporary workaround for an upstream
-Codex issue that breaks Python asyncio cross-thread wakeups inside the
-sandbox. Reboot's main commands (`rbt generate`, `rbt dev run`, and
-related commands) rely on that asyncio behavior.
-
-If you accept the prompt, the installer tags the setting with a
-`# reboot-plugin (managed)` comment so it is easy to find and remove
-later. If you decline, the Codex install is skipped because the
-plugin's main commands will not work reliably under the current
-sandbox behavior.
-:::
-
-Restart Codex after installation so the new plugin, skills, hooks, and
-PATH configuration are loaded.
-
-  </TabItem>
-  <TabItem value="manual" label="Manual install">
-
-Register the Reboot plugin marketplace and install the plugin yourself:
-
-```sh
-codex plugin marketplace add reboot-dev/reboot-plugin
-```
-
-```sh
-codex plugin add reboot@reboot-plugin
-```
-
-Then add the required Codex settings to `~/.codex/config.toml`. Codex
-prints the plugin install path in `codex plugin list`; use it to build
-the PATH entry for your machine:
-
-```sh
-REBOOT_PLUGIN_ROOT="$(codex plugin list \
-  | awk '$1 == "reboot@reboot-plugin" {print $NF; exit}')"
-
-printf 'features.hooks = true\n'
-printf 'shell_environment_policy.set.PATH = "%s/bin:%s"\n' \
-  "$REBOOT_PLUGIN_ROOT" "$PATH"
-printf 'sandbox_mode = "danger-full-access"\n'
-```
-
-Copy the output into `~/.codex/config.toml`, at the **top** of the
-file (dotted keys pasted below a `[table]` header would become part of
-that table). It should look like this, with your actual plugin path:
-
-```toml
-features.hooks = true
-shell_environment_policy.set.PATH = "/path/from/codex/plugin/list/bin:/your/existing/path"
-sandbox_mode = "danger-full-access"
-```
-
-:::warning Merge with your existing config
-TOML forbids defining the same key or table twice, and Codex refuses
-to start on such a config ("duplicate key"). If your config already
-has a `[features]` or `[shell_environment_policy]` table, or already
-sets `sandbox_mode`, set the values inside your existing tables
-instead of pasting the dotted keys above — e.g. add `hooks = true`
-under your `[features]` table.
-:::
-
-Restart Codex after changing the config.
-
-  </TabItem>
-</Tabs>
-
-## Use the skill
-
-In Codex, you do not need a slash command. Start from a normal prompt:
-
-```
-Build a Reboot web app where users can sign up and keep a list of chat rooms
-```
-
-Codex selects the Reboot app skill from the prompt and routes to the
-Web App builder — "web app" (or "website", "SPA", "in the browser",
-or a URL) is what tells it you want a standalone browser frontend
-rather than an AI Chat App. If your description doesn't say, it asks
-first. The builder settles the design before it writes any code. It
-will:
-
-1. Analyze your description and propose a state model.
-2. Map out the application types, methods, the pages the frontend
-   needs, and how users sign in.
-3. State that design back to you — so you can redirect it before
-   the code exists.
-
-Codex then scaffolds the full project — API definition, backend
-servicers, React SPA, and configuration — builds it, writes and runs
-backend tests, and starts the app.
-
-:::info The agent-driven path builds a Python backend
-The skill scaffolds a Python backend with a React frontend. If you
-want a **TypeScript** backend, follow the hand-written
-[TypeScript guide](/full_stack_apps/typescript) instead — but note
-that TypeScript backend support is in alpha.
-:::
-
-## What gets created
-
-The skill generates a complete full-stack Reboot app. The most
-relevant files are:
-
-```
-my-app/
-├── .rbtrc                    # Reboot CLI config
-├── pyproject.toml            # Python deps (uv)
-├── api/
-│   └── my_app/v1/
-│       └── my_app.py         # API definition (Pydantic)
-├── backend/
-│   ├── api/                  # Generated Python bindings
-│   ├── src/
-│   │   ├── main.py           # Application entrypoint
-│   │   └── servicers/
-│   │       └── my_app.py     # Servicer implementation
-│   └── tests/
-│       └── my_app_test.py    # Backend behavior tests
-└── frontend/
-    ├── package.json
-    ├── build.mjs             # Discovers + builds every UI
-    ├── vite.config.ts        # Vite dev server + build config
-    ├── index.css             # Theme variables
-    ├── api/                  # Generated React bindings
-    └── web/                  # The standalone browser SPA
-        ├── index.html
-        ├── .env.development  # VITE_REBOOT_URL=http://localhost:9991
-        └── src/
-            ├── main.tsx      # RebootClientProvider entry
-            └── App.tsx       # Routes + top-level component
-```
-
-Each entity your app manages becomes its own
-[durable state type](/learn_more/define/overview) with its own
-methods; the frontend calls those methods through the typed
-[React hooks](/learn_more/call/from_react) that `rbt generate`
-emits into `frontend/api`. If your app has per-user state, the
-skill also declares a `User` type and signs browser users in
-through Reboot's [built-in OAuth support](/learn_more/auth) —
-`Development()` in development, so you can sign in as any
-identity without registering a provider first.
-
-## Test your app
-
-Codex writes backend unit tests covering your app's user
-stories and runs them before handing the app off — they help to
-make sure that your app works, and keeps working.
-
-Once the tests pass, Codex starts everything the app needs:
-
-* the Reboot backend (`rbt dev run`), which serves your API at
-  `http://localhost:9991`, and
-* the Vite dev server, on `http://localhost:4444`.
-
-It then hands you `http://localhost:4444`, which redirects to your
-web app. In development, click "Sign in" and pick (or make up) a
-`Development` identity; signing in auto-constructs your `User`.
-
-## Iterate on your app
-
-You can use the same skill to modify an existing app:
-
-```
-Add a page that shows the messages in a single chat room.
-```
-
-Codex reads the current Reboot project, proposes a plan, waits for your
-approval, then updates the API, servicers, React pages, and tests.
-
-## Run it again later
-
-If you close Codex and come back to the project later, ask Codex to run
-the Reboot app again:
-
-```
-Run my Reboot app in ./my-app
-```
-
-Or just say "Run this Reboot app" from the project directory. The
-run skill starts the backend and the frontend dev server and points
-you at the app.
-
-## Next steps
-
-* **[Get Started (with Claude Code)](/full_stack_apps/get_started_claude_code)** —
-  the equivalent agent-driven workflow for Claude Code.
-* **[Get Started (Python)](/full_stack_apps/python)** — build a
-  backend step by step to understand every file.
-* **[Build a React frontend](/full_stack_apps/react)** — the
-  hand-written version of the frontend the skill generates.
-* **[Call your API from React](/learn_more/call/from_react)** — the
-  full reference for the generated hooks.
-* **[Full-stack Examples](/full_stack_apps/examples)** — more
-  examples to explore.
-* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — deploy your
-  app with `rbt cloud up`.
-* **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** — ask
-  questions and share what you're building!
diff --git a/documentation/docs/get_started/claude_code.mdx b/documentation/docs/get_started/claude_code.mdx
new file mode 100644
index 000000000..dd75b6240
--- /dev/null
+++ b/documentation/docs/get_started/claude_code.mdx
@@ -0,0 +1,246 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Build with Claude Code
+
+Build a Reboot app with
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
+and the Reboot plugin. You describe what you want, approve the design,
+and Claude Code scaffolds the whole project: API definition, backend
+servicers, frontend, sign-in, tests, and local development setup.
+
+## Install the Reboot plugin
+
+The plugin bundles everything Reboot needs, so Claude Code itself is
+the only prerequisite.
+
+<Tabs groupId="install-method">
+  <TabItem value="quick" label="Quick install">
+
+Install the Reboot plugin for Claude Code with a single command:
+
+```sh
+curl -fsSL https://reboot.dev/install.sh | bash
+```
+
+This registers the Reboot marketplace, installs the plugin, and
+pre-installs its pinned dependencies so your first build runs without
+waiting on downloads.
+
+Then start Claude Code — or, if it was already running while you
+installed, restart it — so the plugin loads.
+
+  </TabItem>
+  <TabItem value="manual" label="Manual install">
+
+Add the marketplace and install the plugin yourself with Claude Code:
+
+```
+claude plugin marketplace add reboot-dev/reboot-plugin
+```
+
+```
+claude plugin install reboot@reboot-plugin
+```
+
+Or, to auto-enable the plugin for your whole team, add this to your
+project's `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "reboot-plugin": {
+      "source": {
+        "source": "github",
+        "repo": "reboot-dev/reboot-plugin"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "reboot@reboot-plugin": true
+  }
+}
+```
+
+Restart any Claude Code session that was already running when you
+installed the Reboot plugin so the new plugin loads.
+
+  </TabItem>
+</Tabs>
+
+## Describe your app
+
+Just say what you want to build, and where you want to use it:
+
+```
+Build me a todo-list app I can use from a browser and from Claude and ChatGPT
+```
+
+That prompt gets you one backend with two front doors: a React web app
+you open in a browser, and an [AI chat app](/surfaces/ai_chat) that
+Claude and ChatGPT can drive as tools — sharing one set of todos and
+one signed-in [`User`](/users/overview) per person.
+
+Claude Code picks the right Reboot skill from your description. The one
+thing it will not guess from the subject matter is **where the app
+lives**, so say it:
+
+| You say | You get |
+| --- | --- |
+| "web app", "website", "SPA", "in the browser", a URL | A [web app](/surfaces/web): a React frontend on its own origin. |
+| "MCP", "in Claude", "in ChatGPT", "chat app" | An [AI chat app](/surfaces/ai_chat): tools and `UI` methods over MCP. |
+| Both, as above | One backend serving both surfaces, with one `User` per person. |
+
+The skills scaffold web and AI chat front ends. A
+[React Native app](/surfaces/react_native) (alpha) is added by hand.
+
+If your description doesn't say, it asks. You can also invoke the
+skills directly:
+
+```
+/reboot:web-app Build me a todo-list app I can use in a browser
+```
+
+```
+/reboot:chat-app Build me a todo-list app I can use from Claude and ChatGPT
+```
+
+Or `/reboot:app` with a description, which asks which surface you
+want and then hands off.
+
+## What it does before it writes code
+
+The skill settles the design first. It will:
+
+1. Analyze your description and propose a state model.
+2. Map out which types and methods your app needs, which pages or UIs
+   the frontend has, and how users sign in.
+3. State that design back to you — so you can redirect it before the
+   code exists.
+
+Then it scaffolds the project, builds it, writes and runs backend
+tests, and starts the app.
+
+:::info The agent-driven path builds a Python backend
+The skills scaffold a Python backend. If you want a **TypeScript**
+backend, follow the hand-written
+[TypeScript guide](/get_started/typescript) instead — but note that
+TypeScript backend support is in alpha.
+:::
+
+## What gets created
+
+A complete Reboot project. The most relevant files:
+
+```
+my-app/
+├── .rbtrc                    # Reboot CLI config
+├── pyproject.toml            # Python deps (uv)
+├── api/
+│   └── my_app/v1/
+│       └── my_app.py         # API definition (Pydantic)
+├── backend/
+│   ├── api/                  # Generated Python bindings
+│   ├── src/
+│   │   ├── main.py           # Application entrypoint, including `oauth=`
+│   │   ├── example_prompts.py  # Chat apps: setup-wizard prompts
+│   │   └── servicers/
+│   │       └── my_app.py     # Servicer implementations
+│   └── tests/
+│       └── my_app_test.py    # Backend behavior tests
+└── frontend/
+    ├── package.json
+    ├── build.mjs             # Discovers + builds every UI
+    ├── vite.config.ts        # Vite dev server + build config
+    ├── index.css             # Theme variables
+    ├── api/                  # Generated React bindings
+    ├── web/                  # The browser SPA
+    │   ├── index.html
+    │   ├── .env.development  # VITE_REBOOT_URL=http://localhost:9991
+    │   └── src/
+    │       ├── main.tsx      # RebootClientProvider entry
+    │       └── App.tsx       # Routes + top-level component
+    └── mcp/                  # Chat apps: one directory per `UI` method
+        └── my-ui/
+            ├── index.html
+            ├── main.tsx
+            └── App.tsx
+```
+
+### Reading the code it wrote
+
+| File | What it is | Learn more |
+| --- | --- | --- |
+| `api/my_app/v1/my_app.py` | Your API: one [durable state type](/define/overview) per entity, each with its methods, declared with Pydantic. | [Define your API](/define/pydantic) |
+| `backend/src/servicers/` | The code behind those methods. | [Implement your API](/implement/servicers) |
+| `backend/src/main.py` | Constructs the `Application` and passes `oauth=`, so people can sign in and Reboot auto-constructs their `User`. | [Users and sign-in](/users/overview) |
+| `frontend/api/` | Typed React hooks generated from your API, shared by every front end. | [Call your API from React](/call/from_react) |
+| `frontend/web/` | The browser app. | [Web apps](/surfaces/web) |
+| `frontend/mcp/` | One React app per `UI` method, rendered inside the chat client. | [AI chat apps](/surfaces/ai_chat) |
+| `backend/tests/` | Backend tests, run against an in-process Reboot. | [Testing](/testing) |
+
+In development the sign-in flow uses `Development()`, a fake account
+picker, so you can sign in as any of a handful of identities without
+registering a provider anywhere. Before you deploy, pick a
+[real provider](/users/providers).
+
+## Test and run
+
+Claude Code writes backend unit tests covering your app's user stories
+and runs them before handing the app off — they help make sure the app
+works, and keeps working.
+
+Once the tests pass it starts everything the app needs:
+
+* the Reboot backend (`rbt dev run`), serving your API at
+  `http://localhost:9991`;
+* the Vite dev server, on `http://localhost:4444`; and
+* for chat apps, a Cloudflare quick tunnel, so cloud-hosted MCP
+  clients can reach your machine.
+
+For a web app it gives you `http://localhost:4444` to open. Click **Sign in**,
+pick a `Development` identity, and Reboot
+[auto-constructs your `User`](/users/overview).
+
+For a chat app it opens the **setup wizard** at
+`http://localhost:9991` — a page your app serves that walks you
+through connecting Claude, ChatGPT, or an inspector, and suggests
+example prompts.
+
+## Iterate
+
+The same skill modifies an existing app:
+
+```
+/reboot:web-app Add due dates to todos, and a filter for what's overdue
+```
+
+It reads your current code, plans the changes, and waits for approval
+before editing.
+
+## Run it again later
+
+Coming back in a new session:
+
+```
+/reboot:run my-app
+```
+
+Or just say "Run this Reboot app" from the project directory.
+
+## Next steps
+
+* **[Build with Codex](/get_started/codex)** — the equivalent
+  agent-driven workflow for Codex.
+* **[Python backend](/get_started/python)** and
+  **[React frontend](/get_started/react)** — build it by hand, to see
+  every file.
+* **[Users and sign-in](/users/overview)** — what the `User` type the
+  skill generated is doing.
+* **[Call your API from React](/call/from_react)** — the full
+  reference for the generated hooks.
+* **[Examples](/get_started/examples)** — more apps to explore.
+* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — ship it with
+  `rbt cloud up`.
+* **[Join the Discord](https://discord.gg/cRbdcS94Nr)** — ask
+  questions and share what you're building!
diff --git a/documentation/docs/get_started/codex.mdx b/documentation/docs/get_started/codex.mdx
new file mode 100644
index 000000000..085a1c465
--- /dev/null
+++ b/documentation/docs/get_started/codex.mdx
@@ -0,0 +1,264 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Build with Codex
+
+Build a Reboot app with [Codex](https://developers.openai.com/codex/)
+and the Reboot plugin. You describe what you want, approve the design,
+and Codex scaffolds the whole project: API definition, backend
+servicers, frontend, sign-in, tests, and local development setup.
+
+## Install the Reboot plugin
+
+The plugin bundles everything Reboot needs, so the only prerequisite
+is [Codex](https://developers.openai.com/codex/cli) itself, installed
+and authenticated.
+
+<Tabs groupId="install-method">
+  <TabItem value="quick" label="Quick install">
+
+Install the Reboot plugin for Codex with a single command:
+
+```sh
+curl -fsSL https://reboot.dev/install.sh | bash
+```
+
+The installer detects Codex, registers the Reboot plugin marketplace,
+installs the plugin, enables Codex hooks, and pre-installs the pinned
+tool shims used by the skill.
+
+:::warning Temporary Codex sandbox opt-out
+The installer currently asks to disable Codex's sandbox globally by
+writing `sandbox_mode = "danger-full-access"` into
+`~/.codex/config.toml`. This is a temporary workaround for an upstream
+Codex issue that breaks Python asyncio cross-thread wakeups inside the
+sandbox. Reboot's main commands (`rbt generate`, `rbt dev run`, and
+related commands) rely on that asyncio behavior.
+
+If you accept the prompt, the installer tags the setting with a
+`# reboot-plugin (managed)` comment so it is easy to find and remove
+later. If you decline, the Codex install is skipped because the
+plugin's main commands will not work reliably under the current
+sandbox behavior.
+:::
+
+Restart Codex after installation so the new plugin, skills, hooks, and
+PATH configuration are loaded.
+
+  </TabItem>
+  <TabItem value="manual" label="Manual install">
+
+Register the Reboot plugin marketplace and install the plugin
+yourself:
+
+```sh
+codex plugin marketplace add reboot-dev/reboot-plugin
+```
+
+```sh
+codex plugin add reboot@reboot-plugin
+```
+
+Then add the required Codex settings to `~/.codex/config.toml`. Codex
+prints the plugin install path in `codex plugin list`; use it to build
+the PATH entry for your machine:
+
+```sh
+REBOOT_PLUGIN_ROOT="$(codex plugin list \
+  | awk '$1 == "reboot@reboot-plugin" {print $NF; exit}')"
+
+printf 'features.hooks = true\n'
+printf 'shell_environment_policy.set.PATH = "%s/bin:%s"\n' \
+  "$REBOOT_PLUGIN_ROOT" "$PATH"
+printf 'sandbox_mode = "danger-full-access"\n'
+```
+
+Copy the output into `~/.codex/config.toml`, at the **top** of the
+file (dotted keys pasted below a `[table]` header would become part of
+that table). It should look like this, with your actual plugin path:
+
+```toml
+features.hooks = true
+shell_environment_policy.set.PATH = "/path/from/codex/plugin/list/bin:/your/existing/path"
+sandbox_mode = "danger-full-access"
+```
+
+:::warning Merge with your existing config
+TOML forbids defining the same key or table twice, and Codex refuses
+to start on such a config ("duplicate key"). If your config already
+has a `[features]` or `[shell_environment_policy]` table, or already
+sets `sandbox_mode`, set the values inside your existing tables
+instead of pasting the dotted keys above — e.g. add `hooks = true`
+under your `[features]` table.
+:::
+
+Restart Codex after changing the config.
+
+  </TabItem>
+</Tabs>
+
+## Describe your app
+
+In Codex you do not need a slash command. Start from a normal prompt:
+
+```
+Build me a Reboot todo-list app I can use from a browser and from Claude and ChatGPT
+```
+
+That prompt gets you one backend with two front doors: a React web app
+you open in a browser, and an [AI chat app](/surfaces/ai_chat) that
+Claude and ChatGPT can drive as tools — sharing one set of todos and
+one signed-in [`User`](/users/overview) per person.
+
+Codex picks the right Reboot skill from your description. The one thing
+it will not guess from the subject matter is **where the app lives**,
+so say it:
+
+| You say | You get |
+| --- | --- |
+| "web app", "website", "SPA", "in the browser", a URL | A [web app](/surfaces/web): a React frontend on its own origin. |
+| "MCP", "in Claude", "in ChatGPT", "chat app" | An [AI chat app](/surfaces/ai_chat): tools and `UI` methods over MCP. |
+| Both, as above | One backend serving both surfaces, with one `User` per person. |
+
+The skills scaffold web and AI chat front ends. A
+[React Native app](/surfaces/react_native) (alpha) is added by hand.
+
+If your description doesn't say, it asks first.
+
+## What it does before it writes code
+
+The builder settles the design first. It will:
+
+1. Analyze your description and propose a state model.
+2. Map out the types, methods, the pages or UIs the frontend needs,
+   and how users sign in.
+3. State that design back to you — so you can redirect it before the
+   code exists.
+
+Then it scaffolds the project, builds it, writes and runs backend
+tests, and starts the app.
+
+:::info The agent-driven path builds a Python backend
+The skills scaffold a Python backend. If you want a **TypeScript**
+backend, follow the hand-written
+[TypeScript guide](/get_started/typescript) instead — but note that
+TypeScript backend support is in alpha.
+:::
+
+## What gets created
+
+A complete Reboot project. The most relevant files:
+
+```
+my-app/
+├── .rbtrc                    # Reboot CLI config
+├── pyproject.toml            # Python deps (uv)
+├── api/
+│   └── my_app/v1/
+│       └── my_app.py         # API definition (Pydantic)
+├── backend/
+│   ├── api/                  # Generated Python bindings
+│   ├── src/
+│   │   ├── main.py           # Application entrypoint, including `oauth=`
+│   │   ├── example_prompts.py  # Chat apps: setup-wizard prompts
+│   │   └── servicers/
+│   │       └── my_app.py     # Servicer implementations
+│   └── tests/
+│       └── my_app_test.py    # Backend behavior tests
+└── frontend/
+    ├── package.json
+    ├── build.mjs             # Discovers + builds every UI
+    ├── vite.config.ts        # Vite dev server + build config
+    ├── index.css             # Theme variables
+    ├── api/                  # Generated React bindings
+    ├── web/                  # The browser SPA
+    │   ├── index.html
+    │   ├── .env.development  # VITE_REBOOT_URL=http://localhost:9991
+    │   └── src/
+    │       ├── main.tsx      # RebootClientProvider entry
+    │       └── App.tsx       # Routes + top-level component
+    └── mcp/                  # Chat apps: one directory per `UI` method
+        └── my-ui/
+            ├── index.html
+            ├── main.tsx
+            └── App.tsx
+```
+
+### Reading the code it wrote
+
+| File | What it is | Learn more |
+| --- | --- | --- |
+| `api/my_app/v1/my_app.py` | Your API: one [durable state type](/define/overview) per entity, each with its methods, declared with Pydantic. | [Define your API](/define/pydantic) |
+| `backend/src/servicers/` | The code behind those methods. | [Implement your API](/implement/servicers) |
+| `backend/src/main.py` | Constructs the `Application` and passes `oauth=`, so people can sign in and Reboot auto-constructs their `User`. | [Users and sign-in](/users/overview) |
+| `frontend/api/` | Typed React hooks generated from your API, shared by every front end. | [Call your API from React](/call/from_react) |
+| `frontend/web/` | The browser app. | [Web apps](/surfaces/web) |
+| `frontend/mcp/` | One React app per `UI` method, rendered inside the chat client. | [AI chat apps](/surfaces/ai_chat) |
+| `backend/tests/` | Backend tests, run against an in-process Reboot. | [Testing](/testing) |
+
+In development the sign-in flow uses `Development()`, a fake account
+picker, so you can sign in as any of a handful of identities without
+registering a provider anywhere. Before you deploy, pick a
+[real provider](/users/providers).
+
+## Test and run
+
+Codex writes backend unit tests covering your app's user stories and
+runs them before handing the app off — they help make sure the app
+works, and keeps working.
+
+Once the tests pass it starts everything the app needs:
+
+* the Reboot backend (`rbt dev run`), serving your API at
+  `http://localhost:9991`;
+* the Vite dev server, on `http://localhost:4444`; and
+* for chat apps, a Cloudflare quick tunnel, so cloud-hosted MCP
+  clients can reach your machine.
+
+For a web app it gives you `http://localhost:4444` to open. Click **Sign in**,
+pick a `Development` identity, and Reboot
+[auto-constructs your `User`](/users/overview).
+
+For a chat app it opens the **setup wizard** at
+`http://localhost:9991` — a page your app serves that walks you
+through connecting Claude, ChatGPT, or an inspector, and suggests
+example prompts.
+
+## Iterate
+
+The same skill modifies an existing app:
+
+```
+Add due dates to todos, and a filter for what's overdue.
+```
+
+Codex reads the current Reboot project, proposes a plan, waits for
+your approval, then updates the API, servicers, React pages, and
+tests.
+
+## Run it again later
+
+Coming back to the project later:
+
+```
+Run my Reboot app in ./my-app
+```
+
+Or just say "Run this Reboot app" from the project directory.
+
+## Next steps
+
+* **[Build with Claude Code](/get_started/claude_code)** — the
+  equivalent agent-driven workflow for Claude Code.
+* **[Python backend](/get_started/python)** and
+  **[React frontend](/get_started/react)** — build it by hand, to see
+  every file.
+* **[Users and sign-in](/users/overview)** — what the `User` type the
+  skill generated is doing.
+* **[Call your API from React](/call/from_react)** — the full
+  reference for the generated hooks.
+* **[Examples](/get_started/examples)** — more apps to explore.
+* **[Deploy to Reboot Cloud](/deploy_on_reboot_cloud)** — ship it with
+  `rbt cloud up`.
+* **[Join the Discord](https://discord.gg/cRbdcS94Nr)** — ask
+  questions and share what you're building!
diff --git a/documentation/docs/get_started/examples.md b/documentation/docs/get_started/examples.md
new file mode 100644
index 000000000..3961e8e0e
--- /dev/null
+++ b/documentation/docs/get_started/examples.md
@@ -0,0 +1,180 @@
+# Examples
+
+Complete Reboot applications to run and take apart. Each one is a real
+project, not a snippet.
+
+## Start here
+
+### `bank-pydantic`
+
+[`reboot-dev/reboot-bank-pydantic`](https://github.com/reboot-dev/reboot-bank-pydantic)
+— _Python backend; React web app, Expo mobile app, and AI chat UIs_
+
+The most complete example, and the one that shows what "general
+purpose" means in practice: **one backend, one `User` per person, and
+three front ends**. A multi-user bank with signup, accounts,
+transfers, and interest.
+
+It demonstrates:
+
+* [Sign-in and `User` auto-construction](/users/overview): signing in
+  enrols the user as a bank customer, in `UserServicer.create`.
+* A [web app](/surfaces/web) under `frontend/web/`, signing in with
+  `useSignIn()` and branching on `useUser()`.
+* A [React Native app](/surfaces/react_native) under
+  `frontend/mobile/`, signing in with `expoAuth(...)` against the same
+  OAuth server — same hooks, same user.
+* [AI chat UIs](/surfaces/ai_chat) under `frontend/mcp/`, so a chat
+  client can open accounts and read balances too.
+* A debit/credit [transaction](/define/methods#kinds) that atomically
+  moves funds between accounts.
+* A [task](/tasks) that pays out interest.
+
+### `chat-room` / `hello`
+
+[`reboot-dev/reboot-hello`](https://github.com/reboot-dev/reboot-hello)
+— _Python backend, React frontend_
+
+The simplest possible app: one singleton chat room, one reactive
+frontend. Open two browsers on the same backend and watch messages
+flow.
+
+It includes:
+
+* A reactive frontend.
+* [Optimistic updates](/call/from_react#optimistic-updates): sent
+  messages render as pending until the backend confirms them.
+* A `Dockerfile` showing how to publish to
+  [Reboot Cloud](/deploy_on_reboot_cloud).
+
+Because of its simplicity it uses no
+[transactions](/define/methods#kinds) — see `bank` or `counter` for
+those.
+
+## Web apps
+
+### `counter`
+
+[`reboot-dev/reboot-counter`](https://github.com/reboot-dev/reboot-counter)
+— _TypeScript backend, React frontend_
+
+The most concise demonstration of a Reboot transaction plus a reactive
+frontend:
+
+* Multiple instances of the same [state type](/define/overview).
+* A [transaction](/define/methods#kinds) that
+  [atomically moves counts between counters](https://github.com/reboot-dev/reboot-counter/blob/ae017cbe980a1f1cbb6002c28828d333e26b7a64/backend/src/counter_servicer.ts#L36-L58).
+* A Next.js frontend using
+  [server components](/call/from_react#nextjs-and-server-components).
+
+### `bank`
+
+[`reboot-dev/reboot-bank`](https://github.com/reboot-dev/reboot-bank)
+— _Python backend, React frontend_
+
+A sibling of `bank-pydantic` that adds the
+[Mailgun integration](/library_services/mailgun), sending an email
+transactionally as part of signup.
+
+### `bank-zod`
+
+[`reboot-dev/reboot-bank-zod`](https://github.com/reboot-dev/reboot-bank-zod)
+— _TypeScript backend, React frontend_
+
+The same bank with its API defined in [Zod](/define/zod).
+
+### `prosemirror-zod`
+
+[`reboot-dev/reboot-prosemirror-zod`](https://github.com/reboot-dev/reboot-prosemirror-zod)
+— _TypeScript backend, React frontend_
+
+Integration with the [ProseMirror](https://prosemirror.net) rich-text
+editor.
+
+It demonstrates:
+
+* How to _sync_ a React frontend with a Reboot backend.
+* A long-lived control loop as a
+  [`workflow`](/define/methods#kinds) method, checkpointing the
+  ProseMirror document.
+
+### `boutique`
+
+[`reboot-dev/reboot-boutique`](https://github.com/reboot-dev/reboot-boutique)
+— _Python backend, React frontend_
+
+The largest example: a fairly complete web shop, factored into
+components that separate teams would plausibly own. Originally forked
+from
+[GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo).
+
+Of particular note:
+
+* A more complex React frontend.
+* Many [state types](/define/overview) and interactions between them.
+* A multi-faceted
+  ["checkout" method](https://github.com/reboot-dev/reboot-boutique/blob/7480e9d6b0a72c560a54f73571c49b10d3fa5478/backend/src/checkout/servicer.py#L45-L149)
+  that transactionally composes calls to many other services — if any
+  part fails, the whole thing aborts atomically.
+* Calls to Reboot-hosted gRPC services.
+
+Start with `hello`, `counter`, or `bank` before this one.
+
+## AI chat apps
+
+### `ai-chat-counter`
+
+[`reboot-dev/reboot/…/ai-chat-counter`](https://github.com/reboot-dev/reboot/tree/main/reboot/examples/ai-chat-counter)
+— _Python backend, React AI chat UIs and a web app_
+
+A counter with visual UIs that run inside ChatGPT, Claude, VS Code, or
+Goose — plus a standalone browser SPA that the chat UI deep-links to.
+
+It demonstrates:
+
+* [`UI` methods](/surfaces/ui_methods) that open React apps in the
+  chat interface.
+* The [`User` type](/users/overview) as an entry point that creates
+  other state types.
+* Generated React hooks (`useCounter()`) working unchanged in both the
+  chat and browser contexts.
+
+Ask [Claude Code](/get_started/claude_code) or
+[Codex](/get_started/codex) to build something like it.
+
+### `chick-potle`
+
+[`reboot-dev/reboot-chick-potle`](https://github.com/reboot-dev/reboot-chick-potle)
+— _Python backend, React AI chat UIs_
+
+A small food-ordering app. The AI calls tools to start an order,
+browse the menu, and change the cart; the human sees a menu grid and a
+cart rendered alongside the conversation.
+
+It demonstrates:
+
+* Two `UI` methods sharing one generated hook (`useFoodOrder()`), so
+  adding an item in one view updates the other immediately.
+* `User.start_order` as a `Transaction` entry point.
+* MCP `Tool`s (`get_menu`, `get_cart`, `add_to_cart`,
+  `remove_from_cart`) that let the AI drive the order.
+
+### `agent-wiki`
+
+[`reboot-dev/reboot-agent-wiki`](https://github.com/reboot-dev/reboot-agent-wiki)
+— _Python backend, React AI chat UIs_
+
+A shared knowledge base that humans and AIs both read and write. Users
+hand in raw conversation transcripts; a background "librarian"
+[agent](/agents) distils them into a small, well-organized set of
+markdown pages.
+
+It demonstrates:
+
+* A long-running [`workflow`](/implement/workflows) (`Wiki.ingest`)
+  acting as a per-wiki background agent.
+* `Transaction`s that atomically create related state across types.
+* Cross-state references as `<StateType>:<state_id>` URIs embedded in
+  markdown, building a page graph with no link table.
+* An in-process test suite driving the librarian with a scripted
+  Pydantic AI `FunctionModel`, so CI needs no real model calls.
diff --git a/documentation/docs/full_stack_apps/python.mdx b/documentation/docs/get_started/python.mdx
similarity index 83%
rename from documentation/docs/full_stack_apps/python.mdx
rename to documentation/docs/get_started/python.mdx
index 3479c1682..4f9626531 100644
--- a/documentation/docs/full_stack_apps/python.mdx
+++ b/documentation/docs/get_started/python.mdx
@@ -1,17 +1,18 @@
 import { CodeStepByStep, Step } from "../../src/components/Steps";
 
-# Python
+# Python backend
 
-If you want to use **Claude Code** to build your full-stack app, see
-the [getting started with Claude Code](get_started_claude_code)
-guide. If you want to use **Codex** to build your app, see the
-[getting started with Codex](get_started_codex) guide. If, however,
-you want to see exactly what we're feeding these AIs, then this
-step-by-step guide is for you!
+Build a Reboot backend in Python, one file at a time. This guide
+covers the backend only; add a frontend with the
+[React guide](/get_started/react).
+
+Prefer to have an agent do it? See
+[Build with Claude Code](/get_started/claude_code) or
+[Build with Codex](/get_started/codex).
 
 <CodeStepByStep>
 <Step
-  title="Setup your app folder"
+  title="Set up your app folder"
   description={`
 
 Create a folder where your Reboot app will live and \`cd\` into it.
@@ -43,7 +44,7 @@ python3 -m venv ./.venv && source .venv/bin/activate && pip install reboot pydan
 
 </Step>
 <Step
-  title="Make sure Docker is running:"
+  title="Make sure Docker is running"
 >
 
 ```sh
@@ -54,15 +55,12 @@ docker ps
   title={<div>Create a Pydantic <code>.py</code> file</div>}
   description={`
 
-Reboot uses an interface definition language (IDL) to define
-your APIs. Currently we support [Pydantic](https://docs.pydantic.dev/)
-and [protocol
-buffers](https://protobuf.dev) (if you're interested in
-[OpenAPI](https://www.openapis.org/) support, please [reach out to us
-on Discord](https://discord.gg/cRbdcS94Nr)).
+You define your API up front. In Python that means
+[Pydantic](https://docs.pydantic.dev/) (in TypeScript it is
+[Zod](https://zod.dev)).
 
 This is where you will define and annotate your durable data
-types and their operations. This example uses Pydantic.
+types and their operations.
 
 `}>
 
@@ -87,8 +85,9 @@ your \`messages\` will be stored.
 
 Next, define the methods on your data type by calling \`Methods\` and
 passing it each method's name, its kind (\`Reader\`, \`Writer\`,
-\`Transaction\`, or \`Workflow\`), and its \`request\` and \`response\`
-classes.
+\`Transaction\`, or \`Workflow\`), its \`request\` and \`response\`
+classes, and whether an AI may call it: \`mcp=Tool()\` exposes it as
+a tool, \`mcp=None\` keeps it out of reach. There is no default.
 
 Lastly, define your API by passing the API \`Type\`, \`ChatRoom\`, to the \`API\`
 function.
@@ -101,19 +100,19 @@ interface, e.g., \`ChatRoom\`. Following these naming conventions will make your
 backend code easy to understand.
 :::
 
-For brevity we are defining just two operations:
+For brevity this defines just two operations:
 
 1. \`messages\` returns all of your messages. It is a
-[\`Reader\`](/learn_more/define/methods#kinds) because it only reads state.
+[\`Reader\`](/define/methods#kinds) because it only reads state.
 1. \`send\` takes a \`message\` and updates state, so it is a
-[\`Writer\`](/learn_more/define/methods#kinds) method.
+[\`Writer\`](/define/methods#kinds) method.
 
 In addition to the operations, you need to define the supporting
 request and response classes, e.g., \`SendRequest\` and
 \`MessagesResponse\`.
 
 :::tip
-[\`Reader\`](/learn_more/define/methods#kinds) methods safely execute concurrently!
+[\`Reader\`](/define/methods#kinds) methods safely execute concurrently!
 :::
 
 `}>
@@ -145,11 +144,13 @@ ChatRoomMethods = Methods(
         request=None,
         response=MessagesResponse,
         description="Every message posted to the room so far.",
+        mcp=None,
     ),
     send=Writer(
         request=SendRequest,
         response=None,
         description="Post one message to the room.",
+        mcp=None,
     ),
 )
 
@@ -167,7 +168,7 @@ api = API(
   description={`
 
 For each of the API types you define, you need to
-implement a [servicer](/learn_more/implement/servicers) - a class containing
+implement a [servicer](/implement/servicers) - a class containing
 methods that implement the operations of your data type.
 
 `}>
@@ -252,7 +253,7 @@ touch ./backend/src/main.py
   description={`
 
 \`Application\` takes a list of the Python
-[\`servicers\`](/learn_more/implement/servicers) that you have implemented.
+[\`servicers\`](/implement/servicers) that you have implemented.
 
 It optionally takes an \`initialize\` function that runs before the app loads,
 which can be used to construct default state.
@@ -319,7 +320,7 @@ Next, tell Reboot how to run your app. Give the app a name via
 \`--application-name=chat-room\` to persist state between app restarts. Watch
 for source code changes via \`--watch=...\` to restart the app whenever there
 is a modification. Finally, tell Reboot that it should use Python to run
-our app.
+your app.
 
 :::tip
 If you do not want state to persist between app restarts, do not pass the
@@ -376,27 +377,31 @@ curl -XPOST http://localhost:9991/chat_room.v1.ChatRoomMethods/Messages \
 </CodeStepByStep>
 
 <!-- TODO: use `## Next steps` instead of `<h1>Next steps</h1>` once
-we figure out to hide the right side navigation/table of contents. -->
+there is a way to hide the right side navigation / table of
+contents. -->
 
 <h1>Next steps</h1>
 
 Well done! You made it!
 
-This example is somewhat contrived as we only created one instance of
+This example is somewhat contrived: it creates just one instance of
 your `ChatRoom` data type, but in practice you are free to make as many
 of these as you like!
 
 Check out these links to continue your exploration:
 
-* **[Build a React frontend](/full_stack_apps/react)** - create a
+* **[Build a React frontend](/get_started/react)** - create a
   React frontend that connects to your backend and displays your
   messages in real-time.
-* **[Learn about transactions](/learn_more/define/methods#kinds)** - so far,
-  we've covered `reader` and
+* **[Add signed-in users](/users/overview)** - declare a `User` type
+  and pass `oauth=` to `Application`; Reboot runs the sign-in flow
+  and auto-constructs a `User` for each person.
+* **[Learn about transactions](/define/methods#kinds)** - so far,
+  you've seen `reader` and
   `writer` methods, but Reboot's power
   extends to `transactions`. [Learn about
   `transactions` and all of the other method kinds
-  here](/learn_more/define/methods#kinds).
+  here](/define/methods#kinds).
 * **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** - to ask
   questions and let us know what you think!
 
diff --git a/documentation/docs/full_stack_apps/react.mdx b/documentation/docs/get_started/react.mdx
similarity index 89%
rename from documentation/docs/full_stack_apps/react.mdx
rename to documentation/docs/get_started/react.mdx
index c991454c0..12d8c80cc 100644
--- a/documentation/docs/full_stack_apps/react.mdx
+++ b/documentation/docs/get_started/react.mdx
@@ -2,7 +2,7 @@ import { CodeStepByStep, Step } from "../../src/components/Steps";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# React
+# React frontend
 
 <CodeStepByStep>
 <Step
@@ -10,8 +10,8 @@ import TabItem from "@theme/TabItem";
   description={`
 
 This guide assumes you've already completed either the
-[Python](/full_stack_apps/python) or
-[TypeScript](/full_stack_apps/typescript) getting started and have
+[Python](/get_started/python) or
+[TypeScript](/get_started/typescript) getting started and have
 a Reboot application running.
 
 `}>
@@ -34,7 +34,7 @@ npx rbt dev run
 </Step>
 
 <Step
-  title="Setup your frontend folder"
+  title="Set up your frontend folder"
   description={`
 
 Create a folder for your React frontend and \`cd\` into it.
@@ -291,8 +291,8 @@ import "./App.css";
   description={`
 
 Make sure your Reboot application is running (for
-[Python](/full_stack_apps/python) or
-[TypeScript](/full_stack_apps/typescript)), then start your React
+[Python](/get_started/python) or
+[TypeScript](/get_started/typescript)), then start your React
 development server.
 
 `}>
@@ -350,21 +350,25 @@ backend sleep for a few seconds in the `send` method!
 </CodeStepByStep>
 
 <!-- TODO: use `## Next steps` instead of `<h1>Next steps</h1>` once
-we figure out to hide the right side navigation/table of contents. -->
+there is a way to hide the right side navigation / table of
+contents. -->
 
 <h1>Next steps</h1>
 
 Well done! You made it! Check out these links to continue your exploration:
 
-* **[Learn advanced React usage](/learn_more/call/from_react)** - like [error
-  handling](/learn_more/call/from_react#errors), or [Next.js and Server
-  Components](/learn_more/call/from_react#nextjs-and-server-components).
-* **[Learn about transactions](/learn_more/define/methods#kinds)** - so far,
-  we've covered `reader` and
+* **[Add sign-in](/surfaces/web#signing-in)** - `useSignIn()` and
+  the generated `useUser()` hook, once your backend has a
+  [`User` type](/users/overview).
+* **[Learn advanced React usage](/call/from_react)** - like [error
+  handling](/call/from_react#errors), or [Next.js and Server
+  Components](/call/from_react#nextjs-and-server-components).
+* **[Learn about transactions](/define/methods#kinds)** - so far,
+  you've seen `reader` and
   `writer` methods, but Reboot's power
   extends to `transactions`. [Learn about
   `transactions` and all of the other method kinds
-  here](/learn_more/define/methods#kinds).
+  here](/define/methods#kinds).
 * **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** - to ask
   questions and let us know what you think!
 
diff --git a/documentation/docs/full_stack_apps/typescript.mdx b/documentation/docs/get_started/typescript.mdx
similarity index 85%
rename from documentation/docs/full_stack_apps/typescript.mdx
rename to documentation/docs/get_started/typescript.mdx
index ed0f06a90..bcc7cc92c 100644
--- a/documentation/docs/full_stack_apps/typescript.mdx
+++ b/documentation/docs/get_started/typescript.mdx
@@ -2,24 +2,26 @@ import { CodeStepByStep, Step } from "../../src/components/Steps";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# TypeScript
+# TypeScript backend
 
 :::warning[TypeScript backend support is in alpha]
 
 The core of Reboot — durable state, transactions, workflows, tasks,
 and the [standard library](/library_services/overview) — works in
 both Python and TypeScript, but some features are currently
-Python-only, including [MCP apps](/learn_more/mcp_apps),
-[`UI` methods](/learn_more/implement/ui_methods), the built-in OAuth
-sign-in flow, and [durable agents](/learn_more/agents). If you don't
-have a strong preference for TypeScript, we recommend
-[starting with Python](/full_stack_apps/python).
+Python-only, including [AI chat apps](/surfaces/ai_chat),
+[`UI` methods](/surfaces/ui_methods), the
+[built-in OAuth sign-in flow](/users/oauth) — and therefore
+[`User` auto-construction](/users/overview) — and
+[durable agents](/agents). If you don't have a strong preference for
+TypeScript, prefer
+[starting with Python](/get_started/python).
 
 :::
 
 <CodeStepByStep>
 <Step
-  title="Setup your app folder"
+  title="Set up your app folder"
   description={`
 
 Create a folder where your Reboot app will live and \`cd\` into it.
@@ -49,7 +51,7 @@ npm init -y && npm pkg set type="module" && npm install @reboot-dev/reboot zod@^
 
 </Step>
 <Step
-  title="Make sure Docker is running:"
+  title="Make sure Docker is running"
 >
 
 ```sh
@@ -60,12 +62,11 @@ docker ps
   title={<div>Define your API using Zod</div>}
   description={`
 
-With Reboot you define your API first, either using
-[Zod](https://zod.dev) or an interface definition language (IDL) like
-[protocol buffers](https://protobuf.dev).
+You define your API up front. In TypeScript that means
+[Zod](https://zod.dev) (in Python it is
+[Pydantic](https://docs.pydantic.dev/)).
 
-In this quickstart we'll use Zod, so we'll need to create a new
-TypeScript file to define the API.
+Create a new TypeScript file to define the API.
 
 This is where you will define and annotate your durable state data
 types and their operations.
@@ -88,15 +89,15 @@ First, import Zod via \`import { z } from "zod/v4"\`. Reboot requires
 Next, define a durable state data type in Reboot called \`ChatRoom\` with
 \`state\` that includes an array of \`string\` messages.
 
-For brevity we are defining just two operations:
+For brevity this defines just two operations:
 
-1. \`messages\` returns all of your messages. It is a [\`reader\`](/learn_more/define/methods#kinds) method because all it does is read state.
-1. \`send\` takes a \`message\` and updates state, so it is a [\`writer\`](/learn_more/define/methods#kinds) method.
+1. \`messages\` returns all of your messages. It is a [\`reader\`](/define/methods#kinds) method because all it does is read state.
+1. \`send\` takes a \`message\` and updates state, so it is a [\`writer\`](/define/methods#kinds) method.
 
 &nbsp;
 
 :::tip
-Methods of kind [\`reader\`](/learn_more/define/methods#kinds) will safely be executed concurrently!
+Methods of kind [\`reader\`](/define/methods#kinds) will safely be executed concurrently!
 :::
 
 `}>
@@ -140,8 +141,8 @@ export const api = {
   title={<div>Create <code>.ts</code> implementation file</div>}
   description={`
 
-For each of the types that we define we need to
-implement [servicers](/learn_more/implement/servicers) - a class containing
+For each type you define you need to
+implement [servicers](/implement/servicers) - a class containing
 methods that implement the operations of your data type.
 
 `}>
@@ -259,7 +260,7 @@ touch ./backend/src/main.ts
   description={`
 
 \`Application\` takes a list of the TypeScript
-[\`servicers\`](/learn_more/implement/servicers) that you have implemented.
+[\`servicers\`](/implement/servicers) that you have implemented.
 
 It optionally takes an \`initialize\` function that runs before the app loads,
 which can be used to construct default state.
@@ -332,7 +333,7 @@ and where to output the generated code, also in \`api/\`.
 
 Next, tell Reboot how to run your app. Give the app a name via
 \`--application-name=chat-room\` to persist state between app restarts. Finally,
-tell Reboot that it should use Node.js to run our app.
+tell Reboot that it should use Node.js to run your app.
 
 :::tip
 If you want to remove all of your changes between app restarts, do not pass the
@@ -390,27 +391,31 @@ curl -XPOST http://localhost:9991/chat_room.v1.ChatRoomMethods/Messages \
 </CodeStepByStep>
 
 <!-- TODO: use `## Next steps` instead of `<h1>Next steps</h1>` once
-we figure out to hide the right side navigation/table of contents. -->
+there is a way to hide the right side navigation / table of
+contents. -->
 
 <h1>Next steps</h1>
 
 Well done! You made it!
 
-This example is somewhat contrived as we only created one instance of
+This example is somewhat contrived: it creates just one instance of
 your `ChatRoom` data type, but in practice you are free to make as many
 of these as you like!
 
 Check out these links to continue your exploration:
 
-* **[Build a React frontend](/full_stack_apps/react)** - create a
+* **[Build a React frontend](/get_started/react)** - create a
   React frontend that connects to your backend and displays your
   messages in real-time.
-* **[Learn about transactions](/learn_more/define/methods#kinds)** - so far,
-  we've covered `reader` and
+* **[Authenticate callers](/users/tokens)** - verify bearer tokens
+  with a `TokenVerifier` and decide who may call what with
+  [authorizers](/users/authorization).
+* **[Learn about transactions](/define/methods#kinds)** - so far,
+  you've seen `reader` and
   `writer` methods, but Reboot's power
   extends to `transactions`. [Learn about
   `transactions` and all of the other method kinds
-  here](/learn_more/define/methods#kinds).
+  here](/define/methods#kinds).
 * **[Join us on Discord](https://discord.gg/cRbdcS94Nr)** - to ask
   questions and let us know what you think!
 
diff --git a/documentation/docs/learn_more/idempotency.mdx b/documentation/docs/idempotency.mdx
similarity index 81%
rename from documentation/docs/learn_more/idempotency.mdx
rename to documentation/docs/idempotency.mdx
index 8995f1318..10dbe0500 100644
--- a/documentation/docs/learn_more/idempotency.mdx
+++ b/documentation/docs/idempotency.mdx
@@ -8,8 +8,8 @@ import TabItem from "@theme/TabItem";
 Calls from code generated for React will use idempotency keys by
 default. Within Reboot, you only need to manually handle idempotency
 if you're trying to retry things manually in a client (using
-[`ExternalContext`](/learn_more/call/from_outside_your_app)) or when
-writing a [`workflow`](/learn_more/implement/workflows) method (using
+[`ExternalContext`](/call/from_outside_your_app)) or when
+writing a [`workflow`](/implement/workflows) method (using
 `WorkflowContext`, which is automatically retried).
 
 If you're only trying to call a method of a specific state _once_
@@ -23,8 +23,8 @@ distinguish each call, for example:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../tests/reboot/idempotency_tests.py&lines=370-373) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/idempotency_tests.py -->
+(CODE:src=../../tests/reboot/idempotency_tests.py&lines=370-373) -->
+<!-- The below code snippet is automatically added from ../../tests/reboot/idempotency_tests.py -->
 
 ```py
 await bank.idempotently('sign up jonathan').SignUp(
@@ -37,8 +37,8 @@ await bank.idempotently('sign up jonathan').SignUp(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../tests/reboot/nodejs/greeter_test/test.ts&lines=64-68) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/nodejs/greeter_test/test.ts -->
+(CODE:src=../../tests/reboot/nodejs/greeter_test/test.ts&lines=64-68) -->
+<!-- The below code snippet is automatically added from ../../tests/reboot/nodejs/greeter_test/test.ts -->
 
 ```ts
 await Greeter.idempotently("generated").create(context, {
diff --git a/documentation/docs/learn_more/applications.mdx b/documentation/docs/implement/application.mdx
similarity index 75%
rename from documentation/docs/learn_more/applications.mdx
rename to documentation/docs/implement/application.mdx
index 62e2df63d..95e14bf8b 100644
--- a/documentation/docs/learn_more/applications.mdx
+++ b/documentation/docs/implement/application.mdx
@@ -95,33 +95,65 @@ const initialize = async (context) => {
 If you have declared an `initialize` function, then you can additionally pass an
 `initialize_bearer_token` (`initializeBearerToken` in TypeScript). That token is used
 to construct the context passed to `initialize`, so that the calls `initialize` makes
-are [authenticated](/learn_more/auth) to your application.
+are [authenticated](/users/authorization) to your application.
 
-## AI Chat App auto-registration
+## Signing users in
 
-When your API includes a
-[`User`](/learn_more/define/pydantic#special-state-user) type or
-[`UI`](/learn_more/implement/ui_methods) methods, `Application`
-automatically registers the necessary endpoints for AI chat
-clients. No extra configuration is needed in your `main.py` —
-the standard `Application(servicers=[...])` pattern handles
-everything:
+Pass an [`OAuth`](/users/oauth) to have Reboot run an OAuth server for
+your application — the sign-in flow for browsers, native apps, and AI
+chat clients alike, plus
+[`User` auto-construction](/users/overview):
 
 ```python
+from reboot.aio.auth.oauth import OAuth
+from reboot.aio.auth.oauth_providers import (
+    Development,
+    Google,
+    OAuthProviderByEnvironment,
+)
+
 application = Application(
     servicers=[UserServicer, CounterServicer],
+    oauth=OAuth(
+        provider=OAuthProviderByEnvironment(
+            dev=Development(),
+            prod=Google(...),
+        ),
+        allowed_origins=["https://app.example.com"],
+    ),
 )
 await application.run()
 ```
 
-AI chat clients connect to your app at `/mcp`. See
-[MCP Apps](/learn_more/mcp_apps) for how your methods are exposed to
-AI chat clients.
+An application whose API declares a `User` type must configure this;
+starting without it is an error rather than a silent fallback. To
+verify tokens minted somewhere else instead, see
+[Bearer tokens](/users/tokens).
+
+## Presenting your app
+
+Three optional arguments describe your application to the clients that
+connect to it — most visibly [AI chat clients](/surfaces/ai_chat) and
+the setup wizard your app serves at its root URL:
+
+| Argument | Description |
+| --- | --- |
+| `title` | A human-readable name. Defaults to the application name. |
+| `description` | What the application does, in a sentence. |
+| `example_prompts` | `ExamplePrompt`s that give a first-time visitor something to try. |
+
+## The MCP endpoint
+
+`Application` mounts an MCP endpoint at `/mcp`, so any
+[AI chat client](/surfaces/ai_chat) can connect. Methods declared with
+`mcp=Tool()` appear there as tools, and
+[`UI`](/surfaces/ui_methods) methods as tools plus resources. No extra
+configuration is needed in your `main.py`.
 
 ## HTTP custom routes
 
 Using a Reboot `Application` you can not only run your Reboot
-[servicers](/learn_more/implement/servicers) but you can also
+[servicers](/implement/servicers) but you can also
 provide custom HTTP route handlers for circumstances where you can't
 just call one of your data type's methods.
 
@@ -139,8 +171,8 @@ implemented with [Express.js](https://expressjs.com/).
 show a helpful page explaining that this is a Reboot
 application.
 
-Please reach out to us at team@reboot.dev if you run into use cases
-for fixing these!
+Reach out at team@reboot.dev if you run into use cases for fixing
+these!
 
 :::
 
@@ -179,18 +211,18 @@ application.http.get("/hello_world", async (context, req, res) => {
 </Tabs>
 
 To simplify calling directly into your Reboot application from your
-`application.http.get` and `application.http.post` handlers we provide
-a `context` of type
-[`ExternalContext`](/learn_more/call/from_outside_your_app) because
+`application.http.get` and `application.http.post` handlers, Reboot
+provides a `context` of type
+[`ExternalContext`](/call/from_outside_your_app), because
 you are still "external" to your application from an authorization
 perspective.
 
 This `context` includes any bearer token from
 `Authorization: Bearer <token>` so that any calls into your Reboot application
-will be properly authorized. In TypeScript, we inject the context for every
-handler. In Python, we follow the FastAPI dependency injection strategy:
-if you want the `context`, you must explicitly add it to your handler's
-arguments as shown in the following example:
+will be properly authorized. In TypeScript, the context is injected into
+every handler. In Python, Reboot follows the FastAPI dependency
+injection strategy: if you want the `context`, you must explicitly add
+it to your handler's arguments as shown in the following example:
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python">
diff --git a/documentation/docs/learn_more/implement/readers.mdx b/documentation/docs/implement/readers.mdx
similarity index 100%
rename from documentation/docs/learn_more/implement/readers.mdx
rename to documentation/docs/implement/readers.mdx
diff --git a/documentation/docs/learn_more/implement/servicers.mdx b/documentation/docs/implement/servicers.mdx
similarity index 78%
rename from documentation/docs/learn_more/implement/servicers.mdx
rename to documentation/docs/implement/servicers.mdx
index 6ddfc59ba..36330b929 100644
--- a/documentation/docs/learn_more/implement/servicers.mdx
+++ b/documentation/docs/implement/servicers.mdx
@@ -5,13 +5,12 @@ import TabItem from "@theme/TabItem";
 
 For each of your data types you need to implement its methods. You do
 that by implementing server-side (backend) **servicers** based on the
-data types and methods you defined (e.g., using
-[Pydantic](/learn_more/define/pydantic),
-[Zod](/learn_more/define/zod), or
-[protobuf](/learn_more/define/protobuf)).
+data types and methods you defined (using
+[Pydantic](/define/pydantic) in Python or
+[Zod](/define/zod) in TypeScript).
 
 :::note
-[`UI`](/learn_more/implement/ui_methods) methods have no backend
+[`UI`](/surfaces/ui_methods) methods have no backend
 servicer code — the React `App.tsx` component is the
 implementation. You only implement `reader`, `writer`,
 `transaction`, and `workflow` methods in the servicer.
@@ -60,7 +59,7 @@ class AccountServicer extends Account.Servicer {
 Each method gets passed:
 
 - `context`: a subclass of
-[`Context`](/learn_more/call/from_within_your_app) specific to the
+[`Context`](/call/from_within_your_app) specific to the
 method kind (e.g., `ReaderContext`)
 - `request`: the type defined in your API file
 
@@ -76,7 +75,7 @@ of your methods:
 When creating a subclass of `Servicer`, there is a 1-1 mapping
 between an instance of your subclass and an instance of your data type
 that was either
-[implicitly or explicitly created](/learn_more/call/overview#constructing-instances).
+[implicitly or explicitly created](/call/overview#constructing-instances).
 
 When using object literals in TypeScript, a single servicer may
 handle many different instances of your data types differentiated by
@@ -86,7 +85,7 @@ different `state` arguments.
 
 For more details on how to implement your methods see:
 
-- [`reader`](/learn_more/implement/readers)
-- [`writer`](/learn_more/implement/writers)
-- [`transaction`](/learn_more/implement/transactions)
-- [`workflow`](/learn_more/implement/workflows)
+- [`reader`](/implement/readers)
+- [`writer`](/implement/writers)
+- [`transaction`](/implement/transactions)
+- [`workflow`](/implement/workflows)
diff --git a/documentation/docs/learn_more/implement/transactions.mdx b/documentation/docs/implement/transactions.mdx
similarity index 83%
rename from documentation/docs/learn_more/implement/transactions.mdx
rename to documentation/docs/implement/transactions.mdx
index a222f989d..2b987aa95 100644
--- a/documentation/docs/learn_more/implement/transactions.mdx
+++ b/documentation/docs/implement/transactions.mdx
@@ -26,8 +26,8 @@ another:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&lines=45-56) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
+(CODE:src=../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&lines=45-56) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
 
 ```py
 async def transfer(
@@ -50,8 +50,8 @@ async def transfer(
     <Tabs groupId="typescript-object-class">
       <TabItem value="object" label="Object literal">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/transactions.ts&lines=66-78) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/transactions.ts -->
+(CODE:src=../../../tests/reboot/documentation/transactions.ts&lines=66-78) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/transactions.ts -->
 
 ```ts
 transfer: async (
@@ -73,8 +73,8 @@ transfer: async (
       </TabItem>
       <TabItem value="class" label="Class">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=46-57) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
+(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=46-57) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
 
 ```ts
 async transfer(
@@ -104,8 +104,8 @@ method for `Bank` that stores the account IDs:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&lines=40-41) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
+(CODE:src=../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py&lines=40-41) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/src/bank_servicer.py -->
 
 ```py
 # Transactions like writers can alter state directly.
@@ -124,8 +124,8 @@ state.accountIds.push(newAccountId);
       </TabItem>
       <TabItem value="class" label="Class">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=35-36) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
+(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts&lines=35-36) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/bank_servicer.ts -->
 
 ```ts
 // Transactions like writers can alter state directly.
@@ -140,6 +140,6 @@ this.state.accountIds.push(newAccountId);
 </Tabs>
 
 In addition to returning a response and updating state, a
-`transaction` can also schedule [async tasks](/learn_more/tasks), which
+`transaction` can also schedule [async tasks](/tasks), which
 are atomically started (or enqueued) if and only if the `transaction`
 completes successfully.
diff --git a/documentation/docs/learn_more/implement/workflows.mdx b/documentation/docs/implement/workflows.mdx
similarity index 91%
rename from documentation/docs/learn_more/implement/workflows.mdx
rename to documentation/docs/implement/workflows.mdx
index bd021be1a..8bd510af2 100644
--- a/documentation/docs/learn_more/implement/workflows.mdx
+++ b/documentation/docs/implement/workflows.mdx
@@ -13,9 +13,9 @@ methods in Reboot:
   be visible to other Reboot methods before the workflow completes. Similarly, a
   workflow can obtain multiple read snapshots over the course of its
   execution. See below for how to
-  [read](/learn_more/implement/workflows#reading-state) and
-  [write](/learn_more/implement/workflows#writing-state) state.
-* Workflows can only be run as [tasks](/learn_more/tasks). This means that
+  [read](/implement/workflows#reading-state) and
+  [write](/implement/workflows#writing-state) state.
+* Workflows can only be run as [tasks](/tasks). This means that
   workflows execute asynchronously and independently from the request/response
   flow associated with normal Reboot method execution.
 
@@ -23,7 +23,7 @@ methods in Reboot:
 
 Unlike other kinds of methods, a `workflow` can only be run as a task, which will
 be retried until it completes successfully (or [aborts with a declared
-error](/learn_more/errors)).
+error](/errors)).
 
 :::note
 
@@ -89,7 +89,7 @@ If you want to make the call _every time_, use `.always()`:
 </Tabs>
 
 Learn more about idempotency when calling a method
-[here](/learn_more/idempotency).
+[here](/idempotency).
 
 ## Reading `state`
 
@@ -100,8 +100,8 @@ _snapshot_:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.py&lines=63-63) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.py -->
+(CODE:src=../../../tests/reboot/documentation/task.py&lines=63-63) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.py -->
 
 ```py
 snapshot = await TestTask.ref().read(context)
@@ -111,8 +111,8 @@ snapshot = await TestTask.ref().read(context)
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.ts&lines=62-62) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.ts -->
+(CODE:src=../../../tests/reboot/documentation/task.ts&lines=62-62) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.ts -->
 
 ```ts
 const snapshot = await TestTask.ref().read(context);
@@ -144,8 +144,8 @@ read-only. If you want to modify state, you must do so explicitly:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.py&lines=75-83) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.py -->
+(CODE:src=../../../tests/reboot/documentation/task.py&lines=75-83) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.py -->
 
 ```py
 async def increment(state):
@@ -163,8 +163,8 @@ await TestTask.ref().idempotently(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.ts&lines=84-88) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.ts -->
+(CODE:src=../../../tests/reboot/documentation/task.ts&lines=84-88) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.ts -->
 
 ```ts
 await TestTask.ref()
@@ -219,8 +219,8 @@ non-empty:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.py&lines=93-97) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.py -->
+(CODE:src=../../../tests/reboot/documentation/task.py&lines=93-97) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.py -->
 
 ```py
 async def have_messages():
@@ -234,8 +234,8 @@ await until("Have messages", context, have_messages)
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.ts&lines=156-159) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.ts -->
+(CODE:src=../../../tests/reboot/documentation/task.ts&lines=156-159) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.ts -->
 
 ```ts
 await until("Have messages", context, async () => {
@@ -270,8 +270,8 @@ collection such as [`SortedMap`](/library_services/sorted_map) or
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.py&lines=99-109) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.py -->
+(CODE:src=../../../tests/reboot/documentation/task.py&lines=99-109) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.py -->
 
 ```py
 async def value_is_stored():
@@ -291,8 +291,8 @@ value = await until(
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../tests/reboot/documentation/task.ts&lines=161-170) -->
-<!-- The below code snippet is automatically added from ../../../../tests/reboot/documentation/task.ts -->
+(CODE:src=../../../tests/reboot/documentation/task.ts&lines=161-170) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/task.ts -->
 
 ```ts
 const value = await until(
diff --git a/documentation/docs/learn_more/implement/writers.mdx b/documentation/docs/implement/writers.mdx
similarity index 97%
rename from documentation/docs/learn_more/implement/writers.mdx
rename to documentation/docs/implement/writers.mdx
index 35d02f72d..b59baee6e 100644
--- a/documentation/docs/learn_more/implement/writers.mdx
+++ b/documentation/docs/implement/writers.mdx
@@ -74,6 +74,6 @@ class AccountServicer extends Account.Servicer {
 </Tabs>
 
 In addition to returning a response and updating state, a `writer` can
-also schedule [async tasks](/learn_more/tasks), which are atomically
+also schedule [async tasks](/tasks), which are atomically
 started (or enqueued) if and only if the `writer` completes
 successfully.
diff --git a/documentation/docs/learn_more/auth.mdx b/documentation/docs/learn_more/auth.mdx
deleted file mode 100644
index 5557207c9..000000000
--- a/documentation/docs/learn_more/auth.mdx
+++ /dev/null
@@ -1,411 +0,0 @@
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Authorization
-
-<!-- TODO: Replace all inline code examples with actual real code! -->
-
-## Overview
-
-Reboot has native support for authorizing calls using the widely used
-`Authorization: Bearer` header, as well as via mechanisms like
-cookies.
-
-Depending on your application's requirements, callers might use API
-keys or access tokens (such as JWTs), produced by your choice of
-provider, e.g., [Auth0](https://auth0.com) or
-[Ory](https://www.ory.sh).
-
-## Setting bearer tokens
-
-### From within your app
-
-To include a bearer token for all calls made to a particular state
-instance, you can specify it in `ref()`:
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-```py
-from_account = Account.ref(
-    request.from_account_id,
-    bearer_token=bearer_token,
-)
-```
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-```ts
-const fromAccount = Account.ref(request.fromAccountId, { bearerToken });
-```
-  </TabItem>
-</Tabs>
-
-You can also pass it as an option when doing [explicit
-construction](/learn_more/call/overview#explicit-construction):
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../tests/reboot/auth_tests.py&lines=399-403) -->
-<!-- The below code snippet is automatically added from ../../../tests/reboot/auth_tests.py -->
-
-```py
-bank, _ = await Bank.create(
-    context,
-    SINGLETON_BANK_ID,
-    Options(bearer_token=VALID_JWT),
-)
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-```ts
-const [bank] = await Bank.create(
-  context,
-  SINGLETON_BANK_ID,
-  {},
-  { bearerToken: VALID_JWT }
-);
-```
-<!-- MARKDOWN-AUTO-DOCS:END -->
-  </TabItem>
-</Tabs>
-
-### From React
-
-```tsx
-import { useRebootClient } from "@reboot-dev/reboot-react";
-
-const { setBearerToken } = useRebootClient();
-
-setBearerToken(token);
-```
-
-### Using `ExternalContext`
-
-To include a bearer token on all calls made from an [`ExternalContext`](/learn_more/call/from_outside_your_app),
-or from React generated code, do the following:
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-  ```py
-  context = ExternalContext(
-      name='Example',
-      url='http://localhost:9991',
-      bearer_token=token,
-  )
-  ```
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-  ```typescript
-  const context = new ExternalContext({
-    name: "Example",
-    url: "http://localhost:9991",
-    bearerToken: token,
-  });
-  ```
-  </TabItem>
-</Tabs>
-
-<!-- TODO: It would be good to be able to link to generated API docs here: #1079. -->
-
-## Authorizing calls to your application
-
-Authorization in Reboot is done by first performing [_token
-verification_](/learn_more/auth#token-verification) and then calling any
-[_authorizers_](/learn_more/auth#authorizers).
-
-### Token verification
-
-To verify that a provided token is valid you must provide a
-`TokenVerifier`. A `TokenVerifier` is set globally on your Reboot
-[`Application`](/learn_more/applications) (or on `Reboot.up` in the case
-of unit tests):
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-  ```py
-  async def main():
-      application = Application(
-          servicers=[...],
-          token_verifier=MyTokenVerifier(...),
-      )
-      await application.run()
-  ```
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-  ```typescript
-  new Application({
-    servicers: [...],
-    ...,
-    tokenVerifier: new MyTokenVerifier(...),
-  }).run();
-  ```
-  </TabItem>
-
-</Tabs>
-
-The `TokenVerifier` interface has a single method, which receives the `token` from the
-`Authorization: Bearer` header, and which should return an `Auth` object if the token
-was valid:
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/aio/auth/token_verifiers.py&lines=26-31) -->
-<!-- The below code snippet is automatically added from ../../../reboot/aio/auth/token_verifiers.py -->
-
-```py
-@abstractmethod
-async def verify_token(
-    self,
-    context: ReaderContext,
-    token: Optional[str],
-) -> VerifyTokenResult:
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/nodejs/index.ts&lines=668-671) -->
-<!-- The below code snippet is automatically added from ../../../reboot/nodejs/index.ts -->
-
-```ts
-abstract verifyToken(
-  context: ReaderContext,
-  token?: string
-): Promise<Auth | null>;
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-  </TabItem>
-</Tabs>
-
-In addition to being able to set any arbitrary `properties` on the
-returned `Auth` object that authorizers can consume, there is a
-specific `user_id` (Python), `userId` (TypeScript) property meant to
-indicate that this is a valid user (and its internally represented ID).
-
-:::tip
-
-**Token verification does not necessarily mean user authentication!**
-
-Depending on where/how tokens are generated they may or may not
-indicate that these tokens represent valid users for _your_
-application, just that this token is valid for a user from a
-particular provider. Read the provider's documentation carefully to
-ensure that you are validating the tokens in such a way that they are
-specific to your application.
-
-:::
-
-### Authorizers
-
-After token verification Reboot will call into any provided
-authorizers. You provide an authorizer by implementing the
-`authorizer()` method on your
-[servicers](/learn_more/implement/servicers):
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-```py
-from reboot.aio.auth.authorizers import allow, allow_if
-
-class AccountServicer(Account.Servicer):
-
-    def authorizer(self):
-        return Account.Authorizer(
-            balance=allow_if(any=[is_admin, is_account_owner]),
-            deposit=allow(),
-            withdraw=allow_if(all=[is_account_owner]),
-            ...
-        )
-
-    ...
-```
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-```ts
-import { allow, allowIf } from "@reboot-dev/reboot";
-
-class AccountServicer extends Account.Servicer {
-
-  authorizer() {
-    return new Account.Authorizer({
-      balance: allowIf({ any: [isAdmin, isAccountOwner] }),
-      deposit: allow(),
-      withdraw: allowIf({ all: [isAccountOwner] }),
-      ...
-    });
-  }
-
-  ...
-```
-  </TabItem>
-</Tabs>
-
-When you create an authorizer for a specific state type you provide
-authorizer "rules" for each method, for example,
-[`deny()`](/learn_more/auth#deny), [`allow()`](/learn_more/auth#allow), or
-[`allow_if()`](/learn_more/auth#allow_if).
-
-You can alternatively return a single authorizer rule directly from
-`authorizer()` which will apply to all methods.
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-```py
-from reboot.aio.auth.authorizers import allow_if
-
-class AccountServicer(Account.Servicer):
-
-    def authorizer(self):
-        return allow_if(all=[is_admin])
-
-    ...
-```
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-```ts
-import { allowIf } from "@reboot-dev/reboot";
-
-class AccountServicer extends Account.Servicer {
-
-  authorizer() {
-    return allowIf({ all: [isAdmin] });
-  }
-
-  ...
-```
-  </TabItem>
-</Tabs>
-
-### Authorizer rules
-
-#### `deny()`
-
-An authorizer rule that will deny all requests.
-
-#### `allow()`
-
-An authorizer rule that will allow all requests.
-
-#### `allow_if()`
-
-An authorizer rule that takes a set of authorizer callables, i.e.,
-functions that will perform the authorization. These functions return
-an `Authorizer.Decision`, which is either `Ok`, `PermissionDenied`, or
-`Unauthenticated`. For example, here is an authorizer callable for
-making sure that the token was verified for a valid user:
-
-<Tabs groupId="language">
-  <TabItem value="python" label="Python">
-```py
-from rbt.v1alpha1 import errors_pb2
-
-def is_valid_user(
-    *,
-    context: ReaderContext,
-    state: Optional[Message],
-    request: Optional[Message],
-    **kwargs,
-):
-    if context.auth is None:
-        return errors_pb2.Unauthenticated()
-
-    if await validate_user(context.auth.user_id):
-        return errors_pb2.Ok()
-
-    return errors_pb2.PermissionDenied()
-```
-  </TabItem>
-
-  <TabItem value="typescript" label="TypeScript">
-```ts
-import { errors_pb } from "@reboot-dev/reboot-api";
-
-function isValidUser({ context }: {
-  context: ReaderContext;
-  state?: Message;
-  request?: Message;
-}) {
-  if (!context.auth) {
-    return new errors_pb.Unauthenticated();
-  }
-
-  if (await validateUser(context.auth.userId)) {
-    return new errors_pb.Ok();
-  }
-
-  return new errors_pb.PermissionDenied();
-}
-```
-  </TabItem>
-</Tabs>
-
-:::important
-
-If you want to allow a call only when _all_ of your authorizer
-callables decide `Ok`, pass them via `all`. If you want to allow a
-call if _any_ (even just one) of the authorizer callables decide `Ok`,
-pass them via `any`.
-
-:::
-
-:::note
-
-Verifying a token and running authorizers _should not have effects_,
-so they always receive a `ReaderContext` regardless of the [kind of
-method](/learn_more/define/methods) that they are authorizing
-for.
-
-:::
-
-### Default authorizer
-
-By default, if you don't provide an authorizer by overriding
-`authorizer()`, **only _application internal_ calls are allowed**.
-
-#### `User` type default
-
-The [`User`](/learn_more/define/pydantic#special-state-user) type is
-a special case: its default authorizer also allows calls where
-the caller's `user_id` matches the `User`'s state ID. In other
-words, each user can access their own `User` state without any
-custom authorizer. App-internal calls are allowed as well.
-
-If you need different rules, you can override `authorizer()` as
-with any other state type.
-
-:::important
-
-Why am I seeing log messages about **MISSING AUTHORIZATION**?
-
-To streamline development using `rbt dev`, calls missing authorization
-are **allowed**. When running with `rbt serve` or via `rbt cloud`
-those same calls will be **denied**, so Reboot emits a log warning to
-help you identify those calls.
-
-Implement the `authorizer()` method on your `Servicer` to silence the
-warning.
-
-:::
-
-## Third-party auth providers
-
-Integrating a third-party auth provider like [Auth0](https://auth0.com/docs/quickstarts) or
-[Ory](https://www.ory.sh/docs/getting-started/overview) into your application
-usually involves:
-
-1. Implementing a `TokenVerifier` that [validates access tokens](https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens),
-   and produces `Auth` objects containing any relevant properties.
-2. Providing authorizer rules for your servicers.
-
diff --git a/documentation/docs/learn_more/define/protobuf.mdx b/documentation/docs/learn_more/define/protobuf.mdx
deleted file mode 100644
index 840a26904..000000000
--- a/documentation/docs/learn_more/define/protobuf.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Protobuf
-
-You can use [protocol buffers](https://protobuf.dev) (aka protobuf) to
-define your API for either TypeScript or Python backends.
-
-To declare a data type called `ChatRoom`, put the following in a `.proto`
-file:
-
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/api/chat_room/v1/chat_room.proto&lines=9-13&syntax=protobuf) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/api/chat_room/v1/chat_room.proto -->
-
-```protobuf
-message ChatRoom {
-  option (rbt.v1alpha1.state) = {
-  };
-  repeated string messages = 1;
-}
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-Reboot uses standard [Protobuf definitions](https://protobuf.dev/programming-guides/proto3/), but take note of the `rbt` [options (aka, annotations)](https://protobuf.dev/programming-guides/proto3/#options), which require adding `import "rbt/v1alpha1/options.proto";` to your `.proto` file.
-
-In the above example, `rbt.v1alpha1.state` declares that `message
-ChatRoom` is a Reboot data type.
-
-In addition to defining the data type, you'll also need to define
-operations for that type, for example:
-
-<!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../../reboot/examples/chat-room/api/chat_room/v1/chat_room.proto&lines=14-27&syntax=protobuf) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/chat-room/api/chat_room/v1/chat_room.proto -->
-
-```protobuf
-service ChatRoomMethods {
-  // Returns the current list of recorded messages.
-  rpc Messages(MessagesRequest) returns (MessagesResponse) {
-    option (rbt.v1alpha1.method).reader = {
-    };
-  }
-
-  // Adds a new message to the list of recorded messages.
-  rpc Send(SendRequest) returns (SendResponse) {
-    option (rbt.v1alpha1.method).writer = {
-    };
-  }
-}
-```
-
-<!-- MARKDOWN-AUTO-DOCS:END -->
-
-:::info
-A Reboot service name must end with the suffix `Methods`. By default,
-Reboot associates the service with the state whose name matches the
-part before the suffix, so `ChatRoomMethods` provides the methods for
-`ChatRoom`.
-:::
-
-For each of the `rpc` methods that you declare, you use the
-`rbt.v1alpha1.method` annotation to specify the method
-[kind](/learn_more/define/methods).
-
-Depending on its [kind](/learn_more/define/methods), a method
-might be able to only read (e.g., `reader`) or both read and write
-(e.g., `writer`) the state.
-
-In the example above, `ChatRoom` has just one `reader` and one `writer`
-method, but it can have any number of `reader`, `writer`,
-`transaction`, and `workflow` methods.
-
-To learn more about how you implement each data type's methods see
-[Implement your API](/learn_more/implement/servicers).
diff --git a/documentation/docs/learn_more/identity_and_external_apis.mdx b/documentation/docs/learn_more/identity_and_external_apis.mdx
deleted file mode 100644
index aaf432e15..000000000
--- a/documentation/docs/learn_more/identity_and_external_apis.mdx
+++ /dev/null
@@ -1,305 +0,0 @@
-# Identity and External API Calls
-
-OAuth plays two distinct roles in a Reboot application:
-
-1. **Identity** — establishing *who* is calling, so that
-   `context.auth.user_id` is populated and authorizers can act on it.
-2. **Acting as the user** at an external service — calling their Google
-   Calendar, their GitHub repos, their Slack — using OAuth tokens your
-   application has been granted.
-
-This page walks through the expected flow for both, and what to do for
-external services that don't use OAuth at all.
-
-## Identity: `Application(oauth=...)`
-
-What you pass to `Application(oauth=...)` stands first and foremost for
-**identity**: the provider determines who `context.auth.user_id` says
-the caller is. In an [MCP application](/learn_more/mcp_apps) that principal is **the user**, and
-there is no middle ground — either every user signs in through this
-OAuth flow, or the application has no per-user auth at all.
-
-:::note
-
-The `oauth=` slot currently serves MCP applications (and is Python
-only). Browser-facing web applications integrate an external identity
-provider via `Application(token_verifier=...)` instead — see
-[Authorization](/learn_more/auth).
-
-:::
-
-The slot takes an `OAuthProviderSelector` — not a provider directly —
-so the provider can depend on the run environment:
-
-```py
-import os
-from reboot.aio.auth.oauth import OAuth
-from reboot.aio.auth.oauth_providers import (
-    Development,
-    Google,
-    OAuthProviderByEnvironment,
-)
-
-async def main():
-    await Application(
-        servicers=[UserServicer],
-        oauth=OAuth(
-            provider=OAuthProviderByEnvironment(
-                dev=Development(),
-                prod=Google(
-                    client_id=os.environ.get("GOOGLE_OAUTH_CLIENT_ID"),
-                    client_secret=os.environ.get(
-                        "GOOGLE_OAUTH_CLIENT_SECRET"
-                    ),
-                ),
-            ),
-        ),
-    ).run()
-```
-
-Under `rbt dev run` the `dev` arm is used; everywhere else (`rbt serve`,
-the Reboot Cloud, or any unrecognized environment) the `prod` arm is.
-Both arms must be passed explicitly (though either may be `None`), and
-a selected `None` arm fails at startup — so you can't silently ship
-without choosing a provider.
-
-The providers that ship in `reboot.aio.auth.oauth_providers`:
-
-| Provider        | Identity issued                                   | When to use                                                                                   |
-| --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `Development()` | A stable fake ID per picked account               | Local development only; shows a fake account picker.                                          |
-| `Google(...)`   | The Google account's OIDC `sub` claim             | Users sign in with Google.                                                                    |
-| `GitHub(...)`   | The GitHub user's numeric ID                      | Users sign in with GitHub.                                                                    |
-| `Auth0(...)`    | The Auth0 OIDC `sub` (e.g. `google-oauth2\|108…`) | Multiple sign-in methods behind one provider, or user management beyond a bare user ID.       |
-| `Anonymous()`   | A fresh `anon-{ULID}` per flow                    | No sign-in UI at all; don't launch on it — every returning user gets a brand-new identity.    |
-
-For every real provider, register your application in the provider's
-own console and register Reboot's callback URL —
-`<your-app-base-url>/__/oauth/callback` — as an authorized redirect
-URI. Deliver the client ID/secret as
-[environment variables](/learn_more/secrets), never hard-coded.
-
-:::important
-
-The provider you launch with **fixes your user-ID namespace**. Each
-provider issues IDs in its own space with no mapping between them, so
-switching providers once you have real users strands every user-keyed
-piece of state. Choose deliberately before you have production users.
-
-:::
-
-### Need user management, not just a user ID?
-
-`Google` and `GitHub` give you exactly one thing: a stable
-`context.auth.user_id`. If your application needs more — user profiles,
-email/password accounts, password resets, email verification, MFA,
-blocking users, an admin view of who signed up — don't build that
-yourself. Use `Auth0`: its tenant provides all of it, brokers most
-upstream identity providers (Google, GitHub, enterprise SSO,
-username/password), and your application still sees a single OIDC
-provider.
-
-### Writing your own provider
-
-If no shipped provider fits — your users live in a self-hosted Keycloak,
-an internal SSO, or another identity provider that Auth0 can't broker —
-subclass `RegisteredOAuthProvider` (from
-`reboot.aio.auth.oauth_providers`) and pass an instance in the same
-`dev=` / `prod=` arms. You implement two methods, and Reboot's OAuth
-server does the rest (endpoints, `state` verification, minting your
-application's own tokens):
-
-- `authorization_url(state, redirect_uri)` — build the identity
-  provider's authorize URL, passing `state` and `redirect_uri` through
-  verbatim.
-- `exchange_code(code, redirect_uri)` — exchange the code at the
-  identity provider's token endpoint and return an `ExchangeResult`
-  with the user's ID.
-
-The returned user ID must be **stable**: the same human must get the
-same ID on every sign-in (an OIDC `sub` claim or a numeric account ID —
-never an email address, which can change). It becomes
-`context.auth.user_id` and the key of all user-keyed state, so the
-namespace-permanence warning above applies to your custom provider too.
-
-## Acting as the user at an external service
-
-Calling an external service's API on the user's behalf always has two
-halves:
-
-1. **Capture** the service's OAuth tokens once, stored encrypted in an
-   [`OAuthTokenManager`](/library_services/oauth_token_manager) — one
-   manager per external service.
-2. **Use** them: `fetch` the tokens back and make the outbound API call
-   from a [workflow](/learn_more/implement/workflows).
-
-How you capture depends on *whose* API you want to call.
-
-### Your identity provider's own API: `store_tokens=True`
-
-If the API belongs to the provider you already sign in with, Reboot
-captures its tokens for you. Pass the extra OAuth `scopes=[...]` your
-calls need (on top of the base identity scope the provider always
-requests) and `store_tokens=True`:
-
-```py
-oauth=OAuth(
-    provider=OAuthProviderByEnvironment(
-        # `Development()` issues no tokens, so to exercise the
-        # provider's API locally use the real provider in `dev=` too.
-        dev=_google(),
-        prod=_google(),
-    ),
-)
-
-def _google() -> Google:
-    return Google(
-        client_id=os.environ.get("GOOGLE_OAUTH_CLIENT_ID"),
-        client_secret=os.environ.get("GOOGLE_OAUTH_CLIENT_SECRET"),
-        # Request the least you need.
-        scopes=["https://www.googleapis.com/auth/calendar.events"],
-        store_tokens=True,
-    )
-```
-
-During each sign-in, the OAuth server captures the provider's
-access/refresh tokens at the code exchange and persists them encrypted
-under the matching `OAuthTokenManager` (`GOOGLE` here). Your code only
-ever calls `fetch`. This requires the `oauth`, `ciphertext`, and
-`ordered_map` libraries on your `Application` — see
-[OAuth Token Manager](/library_services/oauth_token_manager).
-
-:::important
-
-**Reboot stores only the provider's *own* tokens.** This matters most
-with `Auth0`: it is a broker, so when a user signs in "with Google"
-through Auth0, what gets stored is an **Auth0** token — it authorizes
-Auth0's own APIs, not Google's. To call the upstream service, either
-retrieve the federated identity provider's token from Auth0 (it keeps
-it on the user's profile, retrievable via Auth0's Management API with
-the `read:user_idp_tokens` scope), or capture the upstream service's
-tokens yourself as described next.
-
-:::
-
-### Any other OAuth service: run its flow yourself
-
-When the service is *not* your identity provider — you sign in with
-Google but want the user's Slack — there is no shortcut: a Google grant
-only authorizes Google's APIs. Run the other service's OAuth flow
-yourself with your own HTTP endpoints, then store what it issues in
-that service's `OAuthTokenManager`, so that **all** of your
-application's OAuth tokens live consistently in the same kind of store:
-
-1. Register an **authorize** route that redirects the browser to the
-   service's authorize URL (your client ID, the scopes you need, your
-   callback as the redirect URI, and a signed `state` carrying the
-   signed-in user's ID).
-2. Register a **callback** route that verifies the `state`, exchanges
-   the `code` at the service's token endpoint, and calls
-   [`OAuthTokenManager.store`](/library_services/oauth_token_manager#store)
-   under a service ID of your choosing (e.g. `"slack.com"`).
-
-Since `OAuthTokenManager`'s methods are application-internal, the
-callback route must opt into an application-internal context:
-
-```py
-# In `main()`, after constructing `application`:
-application.http.get("/__/oauth/slack/authorize")(slack_authorize)
-application.http.get("/__/oauth/slack/callback", app_internal=True)(
-    slack_callback
-)
-```
-
-:::caution
-
-`app_internal=True` bypasses authorizers. Only set it on a route you
-are certain serves trusted traffic — here, a callback that runs only
-after you've verified the OAuth `state` you issued. Never set it on a
-route that acts on unvalidated request input.
-
-:::
-
-### Using the tokens: call the API from a workflow
-
-Reading tokens back and calling the service is the same no matter how
-the tokens were captured — and the outbound HTTP call belongs in a
-[workflow](/learn_more/implement/workflows), wrapped in a durability
-primitive (usually `at_least_once`), like any other
-[side effect](/learn_more/side_effects):
-
-```py
-from rbt.std.oauth.v1.oauth_rbt import OAuthTokenManager
-from reboot.aio.workflows import at_least_once
-from reboot.std.oauth.v1.oauth import GOOGLE
-
-@classmethod
-async def create_event(
-    cls,
-    context: WorkflowContext,
-    request: User.CreateEventRequest,
-) -> User.CreateEventResponse:
-    stored = await OAuthTokenManager.ref(GOOGLE).fetch(
-        context, user_id=context.state_id,
-    )
-    if not stored.found:
-        # Not connected yet: surface a "connect" path, don't crash.
-        return User.CreateEventResponse(connected=False)
-
-    async def do_create():
-        return await calendar_api.create_event(
-            access_token=stored.tokens.access_token,
-            summary=request.summary,
-        )
-
-    result = await at_least_once("Create event", context, do_create)
-    return User.CreateEventResponse(connected=True)
-```
-
-### Services where the user provides an API key instead of OAuth
-
-Some services don't expose per-user OAuth at all — the user pastes an
-API key or personal access token into your UI.
-
-:::note
-
-This section is about a key **the user** provides so your application
-can act *as that user* — a per-user secret, stored per user. A key
-**you, the developer,** hold for the whole application (your Stripe
-secret key, your OpenAI key) is not per-user state and doesn't belong
-in application state at all: deliver it as an application
-[secret](/learn_more/secrets) via environment variables.
-
-:::
-
-`OAuthTokenManager` is
-purpose-built for OAuth tokens; don't shoehorn an API key into it. The
-key is still a secret at rest, so encrypt it with
-[`Ciphertext`](/library_services/ciphertext) and keep the returned
-`Ciphertext` state ID — itself a harmless string — in your state as the
-reference to the encrypted value:
-
-```py
-ciphertext, _ = await Ciphertext.encrypt(
-    context,
-    plaintext=request.api_key.encode(),
-    associated_data=make_associated_data(
-        user_id=user_id, purpose="acme-api-key",
-    ),
-    scope=f"user:{user_id}",  # The crypto-shred unit.
-    key_manager_id=APP_SHARED_KEY_MANAGER_ID,
-)
-# The reference to the encrypted key; never the key itself.
-self.state.acme_api_key_id = ciphertext.state_id
-```
-
-To use it, `decrypt` (with the same `associated_data`) and make the
-call from a workflow, exactly as above.
-
-## Erasing a user's credentials
-
-Both stores support per-user erasure by crypto-shredding: see
-[erasing a user's tokens](/library_services/oauth_token_manager#erasing-a-users-tokens)
-for `OAuthTokenManager`, and
-[crypto-shred](/library_services/ciphertext#crypto-shred-shred) for
-`Ciphertext`-encrypted API keys.
diff --git a/documentation/docs/learn_more/mcp_apps.mdx b/documentation/docs/learn_more/mcp_apps.mdx
deleted file mode 100644
index 95cc10234..000000000
--- a/documentation/docs/learn_more/mcp_apps.mdx
+++ /dev/null
@@ -1,81 +0,0 @@
-# MCP Apps
-
-Reboot AI Chat Apps are **MCP apps** — applications that speak
-[MCP (Model Context Protocol)](https://modelcontextprotocol.io),
-the standard that AI clients use to discover and interact with
-external tools and content.
-
-## What is MCP?
-
-MCP is an open protocol that lets AI clients (ChatGPT, Claude,
-VS Code, Goose, and others) connect to external servers. An MCP
-server exposes **tools** (actions the AI can call) and
-**resources** (content the AI can read or display).
-
-## How Reboot uses MCP
-
-When your Reboot API includes a `User` type, `Application`
-automatically registers an MCP endpoint at `/mcp`. This means:
-
-- **Methods become MCP tools via `mcp=Tool()`.** Any method
-  on any type — including `User` — is exposed as an MCP tool
-  when declared with `mcp=Tool()`. Use `mcp=None` to keep a
-  method hidden from the AI. `User` methods called without a
-  state ID resolve the right `User` from the authenticated user.
-  `User` typically acts as an entry point, with methods that
-  create other state types.
-- **Non-`User` methods work the same way.** Methods on other
-  types (like `Counter`) also use `mcp=Tool()`. The AI receives
-  the state ID when it creates the instance and passes it in
-  subsequent calls.
-- **[`UI`](/learn_more/implement/ui_methods) methods become MCP
-  tools + resources.** When the AI
-  calls a `UI` tool, it receives metadata pointing to a compiled
-  React app (served as an MCP resource) — that prompts the AI to
-  display that app in the chat.
-
-You do not need to write any MCP protocol code. Reboot handles
-serialization, transport, session management, and state routing.
-
-## Controlling which methods are tools
-
-Every method must explicitly declare its MCP exposure: set
-`mcp=Tool()` to expose a method as an MCP tool, or `mcp=None`
-to keep it hidden from the AI. There is no implicit default.
-
-Not every method should be an MCP tool:
-
-1. **Human-only actions.** Some actions should only be triggered
-   by a human — for example, a "Yes, confirm" button in a React
-   UI. The human clicks it to call the method, but the AI
-   cannot.
-2. **Context bloat.** Every tool you expose is added to the AI's
-   context window. Exposing too many tools can overwhelm the AI
-   and degrade its performance.
-
-For the full API reference and code examples, see
-[Creating tools](/learn_more/define/pydantic#creating-tools-for-the-ai).
-
-## Users and `User` state
-
-When an authenticated user connects to your app via MCP, Reboot
-automatically creates a
-[`User`](/learn_more/define/pydantic#special-state-user) state instance
-for that user (if one does not already exist). `User` acts as an entry point: its methods typically
-create other state types (like `Counter`) whose IDs can be stored in the
-`User`'s state. Such IDs can also be returned to the AI, which can use
-them to make further calls (like `Counter.increment()`) directly to
-those states. The AI tracks IDs in its context window, which is scoped
-to the chat conversation. To remember IDs or other info across
-conversations, place it in `User` state and provide methods on `User`
-for the AI to use to fetch that information.
-
-The `User` state ID is derived from the authenticated user's identity
-(e.g. the `sub` claim in an OAuth token). Reboot handles persistence on
-the server side, so state created by a user is durable and accessible
-across sessions and conversations.
-
-## Connecting AI clients
-
-To connect an AI client to your Reboot app, see
-[From an MCP client](/learn_more/call/from_mcp_client).
diff --git a/documentation/docs/library_services/item.mdx b/documentation/docs/library_services/item.mdx
index be3f89cd0..2ad72fd5d 100644
--- a/documentation/docs/library_services/item.mdx
+++ b/documentation/docs/library_services/item.mdx
@@ -13,8 +13,7 @@ There are three ways of formatting data for an `Item`.
     A producer of value is expected to set one of that variants, absence of any
     variant indicates an error. This type is meant to represent all possible JSON values.
   * `bytes` is used to store a string of `bytes`.
-  * `Any` refers to the `Any` protobuf and is the best choice if you are using protobufs
-    to structure your data.
+  * `Any` wraps a protobuf message, for code that already has one.
 
 
 ## Imports
@@ -46,8 +45,8 @@ Since this is a data type that is not stored individually, you do not need a ser
 
 ## Value
 
-`Value` is the recommended way to use `Item` if you have structured data that is
-not already a string of `bytes` or a protobuf.
+`Value` is the recommended way to use `Item` for structured data:
+anything you could express as JSON.
 
 To marshal your data
 * in Python, you can use helper methods from `reboot.protobuf`
@@ -179,8 +178,8 @@ console.log(item.bytes);
 
 ##  Any
 
-If you use protobufs to format your data, you can directly store that
-into an `Item`.
+If you already have a protobuf message, you can store it directly in
+an `Item`.
 
 To pack and unpack from an `Any` protobuf,
 * in Python, you can use helper methods from `reboot.protobuf`
diff --git a/documentation/docs/library_services/mailgun.md b/documentation/docs/library_services/mailgun.md
index 22b75be76..cdb94a284 100644
--- a/documentation/docs/library_services/mailgun.md
+++ b/documentation/docs/library_services/mailgun.md
@@ -20,7 +20,7 @@ application = Application(
 ```
 
 To use the Mailgun integration, set the `MAILGUN_API_KEY`
-environment variable to your Mailgun API key. See [Secrets](../learn_more/secrets.mdx)
+environment variable to your Mailgun API key. See [Secrets](../secrets.mdx)
 for how to set this for local development and for deployments to
 Reboot Cloud.
 
@@ -70,8 +70,8 @@ See `Send`.
 | sender | string | The email address of the sender of the message. |
 | subject | string | The subject of the message. |
 | domain | string | The domain to send from. |
-| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) body.text | string | The body content of the message, as text. |
-| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) body.html | string | The body content of the message, as HTML. |
+| body.text | string | The body content of the message, as text. Set exactly one of `body.text` and `body.html`. |
+| body.html | string | The body content of the message, as HTML. |
 
 
 ### SendResponse {#sendresponse}
diff --git a/documentation/docs/library_services/oauth_token_manager.mdx b/documentation/docs/library_services/oauth_token_manager.mdx
index 28363c104..11182e4a8 100644
--- a/documentation/docs/library_services/oauth_token_manager.mdx
+++ b/documentation/docs/library_services/oauth_token_manager.mdx
@@ -31,7 +31,7 @@ service without one (e.g. `"slack.com"`).
   call them from your own backend, never expose them to untrusted
   clients.
 - If your application authenticates users with
-  [`Application(oauth=...)`](/learn_more/identity_and_external_apis),
+  [`Application(oauth=...)`](/users/external_apis),
   the OAuth server can capture and store the identity provider's tokens
   for you automatically (`store_tokens=True`) — your code then only ever
   calls `fetch`.
@@ -98,7 +98,7 @@ The stored value is an `OAuthTokens` message:
 
 ## Methods
 
-### Fetch
+### `fetch`
 
 A `reader` that returns the stored tokens for a user. `found` is false
 when nothing is stored for that user — or once their tokens have been
@@ -140,7 +140,7 @@ exist yet, so the very first `fetch` can abort with a "state not
 constructed" error rather than report `found: false`. Treat both the
 same way — "this user hasn't connected the service yet".
 
-### Store
+### `store`
 
 A `transaction` that encrypts and persists tokens for a user,
 **replacing** any previously stored ones wholesale — including the
@@ -151,7 +151,7 @@ into the new `tokens` before calling `store`.
 
 You call `store` yourself when you run a service's OAuth flow with your
 own endpoints (see
-[Identity and external API calls](/learn_more/identity_and_external_apis));
+[Identity and external API calls](/users/external_apis));
 with `store_tokens=True` on an `Application(oauth=...)` provider, the
 OAuth server calls it for you — including carrying an existing refresh
 token forward when a later sign-in doesn't return one.
diff --git a/documentation/docs/library_services/ordered_map.mdx b/documentation/docs/library_services/ordered_map.mdx
index d9d12228a..1a1140b58 100644
--- a/documentation/docs/library_services/ordered_map.mdx
+++ b/documentation/docs/library_services/ordered_map.mdx
@@ -13,8 +13,7 @@ when inserted into an `OrderedMap`.
     A producer of a `Value` is expected to set one of these variants; the
     absence of any variant indicates an error. This type is meant to represent all possible JSON values.
   * `bytes` is used to store a string of `bytes`.
-  * `Any` refers to the `Any` protobuf and is the best choice if you are using protobufs
-    to structure your data.
+  * `Any` wraps a protobuf message, for code that already has one.
 
 `OrderedMap`s are frequently used to create indexes of other state types,
 but can also be used to efficiently store large collections of primitive values.
@@ -26,9 +25,8 @@ For example:
   * To index a data type by creation time, you can use time-ordered UUIDs
     (such as UUIDv1 or UUIDv7) as keys and the data type's state-ID as
     values.
-  * To index a large collection of Protobuf message types, you can use a
-    key of your choice and the serialized value of each Protobuf message
-    as a value.
+  * To store a large collection of records, you can use a key of your
+    choice and each record, serialized, as a value.
 
 To use an `OrderedMap` in your application, you typically want to choose an ID for
 the map and store it somewhere (e.g., as a field in the appropriate state data
@@ -88,7 +86,7 @@ new Application({
 
 By default, `OrderedMap` allows internal calls from the application to the
 library. However, this can be overridden by providing your own
-[authorizer](/learn_more/auth#authorizers).
+[authorizer](/users/authorization#writing-an-authorizer).
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
@@ -579,7 +577,7 @@ try {
 
 ## React
 
-Once you've [set up](/learn_more/call/from_react) your React app to call into
+Once you've [set up](/call/from_react) your React app to call into
 your Reboot API, you can also use `OrderedMap` directly from your React app.
 
 First, on your backend, you will need to [override the authorizer](#authorizer) to allow
@@ -644,5 +642,5 @@ if (aborted !== undefined) {
 <!-- MARKDOWN-AUTO-DOCS:END -->
 
 See [Call your API from
-React](/learn_more/call/from_react) to learn more about how to call methods from
+React](/call/from_react) to learn more about how to call methods from
 React.
diff --git a/documentation/docs/library_services/overview.md b/documentation/docs/library_services/overview.md
index e2290ba7d..368d55f74 100644
--- a/documentation/docs/library_services/overview.md
+++ b/documentation/docs/library_services/overview.md
@@ -18,7 +18,7 @@ The current libraries are:
 
 ## Integrations
 
-Reboot's integrations add clean, surefire APIs to interact with third party services. Because interactions with external services are [isolated as side-effects](/learn_more/side_effects), you can confidently use an integration's API -- knowing that it will safely compose, and without worrying about whether it might partially fail or retry unsafely.
+Reboot's integrations add clean, surefire APIs to interact with third party services. Because interactions with external services are [isolated as side-effects](/side_effects), you can confidently use an integration's API -- knowing that it will safely compose, and without worrying about whether it might partially fail or retry unsafely.
 
 The currently supported integrations are:
 * [Mailgun](./mailgun) - Integration that supports sending email messages using the Mailgun API.
diff --git a/documentation/docs/library_services/sorted_map.mdx b/documentation/docs/library_services/sorted_map.mdx
index f5ead399b..1e40f2f2a 100644
--- a/documentation/docs/library_services/sorted_map.mdx
+++ b/documentation/docs/library_services/sorted_map.mdx
@@ -20,9 +20,8 @@ For example:
   * To index a data type by creation time, you can use time-ordered UUIDs
     (such as UUIDv1 or UUIDv7) as keys and the data type's state-ID as
     values.
-  * To index a large collection of Protobuf message types, you can use a
-    key of your choice and the serialized value of each Protobuf message
-    as a value.
+  * To store a large collection of records, you can use a key of your
+    choice and each record, serialized, as a value.
 
 To use a `SortedMap` in your application, you typically want to choose an ID for
 the map and store it somewhere (e.g., as a field in the appropriate state data
diff --git a/documentation/docs/learn_more/nonlocal.md b/documentation/docs/nonlocal.md
similarity index 80%
rename from documentation/docs/learn_more/nonlocal.md
rename to documentation/docs/nonlocal.md
index 2a0698c27..2a3d599f9 100644
--- a/documentation/docs/learn_more/nonlocal.md
+++ b/documentation/docs/nonlocal.md
@@ -82,3 +82,24 @@ command) before changes to the `.env` file take effect.
 
 Now your frontend will access the backend via the tunnel host you've provided,
 making it accessible anywhere on the internet!
+
+### Signing in through a tunnel
+
+If your application signs users in, the tunnel gives your frontend a
+new origin, and credentialed requests from it are refused until that
+origin is trusted. Under `rbt dev run` only `http://localhost` and
+`http://127.0.0.1` are trusted automatically, so add the tunnel's
+frontend origin to [`allowed_origins`](/users/oauth#allowed_origins):
+
+```python
+oauth=OAuth(
+    provider=...,
+    allowed_origins=["https://43ee-20-61-126-210.ngrok-free.app"],
+)
+```
+
+Your identity provider also has to accept the new callback URL, so add
+`https://<your-backend-tunnel>/__/oauth/callback` to its authorized
+redirect URIs. A tunnel that hands out a fresh hostname on every run
+means redoing both each time; a tunnel with a stable hostname is worth
+it if you do this often.
diff --git a/documentation/docs/overview.mdx b/documentation/docs/overview.mdx
index fa6dc90ca..5678c8516 100644
--- a/documentation/docs/overview.mdx
+++ b/documentation/docs/overview.mdx
@@ -6,92 +6,187 @@ slug: /
 import { Card, CardSection } from "../src/components/Cards";
 import ClaudeLogo from "../static/img/claude-logo.svg";
 import CodexLogo from "../static/img/codex-logo.svg";
-import PythonLogo from "../static/img/python-logo.svg";
-import TSLogo from "../static/img/ts-logo.svg";
 
-# Build Apps with Reboot
+# Build apps with Reboot
 
 <div style={{ fontSize: "1.2rem" }}>
-  Reboot lets you build stateful, multiplayer apps on a durable
-  backend. Build full-stack web apps with React frontends, or AI
-  chat apps that run inside ChatGPT, Claude, and VS Code.
+  A full-stack framework for the AI era. Reboot solves the hard
+  problems once, at the framework level, so neither you nor your
+  coding agent has to.
 </div>
 
-## Where your app runs
+## Trust the code your agent writes
 
-The same backend, two different ways to reach your users. Pick a starting
-point:
+Modern app development is quickly becoming AI-assisted, or entirely
+vibe-coded. Agents are blazingly fast junior engineers. They ship
+concurrency and retry bugs. They skip the things you didn't spell
+out: the reactive frontend, the sign-in flow, the retry that should
+have happened. They don't expect their code to crash. And they
+produce diffs you can't easily review. A harness is not enough. They
+need a rock-solid foundation to stand on.
 
-### As a full-stack web app
+Reboot is that foundation. Constraints make entire classes of bugs
+impossible. Durable state, reactive frontends, and signed-in users
+come built in rather than asked for. A crash loses nothing. And the
+semantics are simple enough, for humans and agents alike, that you
+can review what was written.
+
+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.
+
+## What Reboot handles for you
+
+- **Correct concurrency and retry safety.** Every method declares its
+  [kind](/define/methods) — `reader`, `writer`, `transaction`, or
+  `workflow` — and Reboot enforces what each one may do. A read cannot
+  sneak in a write, and a transaction is atomic across state types.
+- **Durable applications.** Not just a durable execution engine:
+  the moment a function returns, its `state` is saved.
+  [Workflows](/implement/workflows) resume where they failed — the
+  steps that already finished are memoized rather than run again — and
+  [transactions](/implement/transactions) keep everything atomic. No
+  database, no cache, no queue.
+- **What agents won't build unless asked.** You asked for a frontend,
+  but what you really wanted was a [reactive](/call/from_react) 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.
+- **Signed-in users.** 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`](/users/overview): the per-user entry
+  point the rest of your app hangs off. No session table, and no
+  glue between the provider and your data.
+- **Semantics you can actually review.** Even if a harness could get
+  an agent to handle all of the above, you would still have to read
+  the diff. Reboot's semantics are simple enough, for humans and
+  agents alike, that you can.
+
+Python backends are supported today. TypeScript backends and
+[React Native](/surfaces/react_native) frontends are in
+[alpha](/get_started/typescript). More languages are coming.
+
+## Get started
+
+The fastest path is to let an agent build it. Install the Reboot
+plugin for Claude Code or Codex:
+
+```sh
+curl -fsSL https://reboot.dev/install.sh | bash
+```
+
+Then describe what you want — "Build me an AI chat app todo list with
+drag-and-drop to reorder", "Build me a scalable messaging app".
 
 <CardSection
-  id="full-stack-apps"
-  description="A reactive Reboot backend behind a standalone React
-  frontend, on its own or as a full-page extension of your chat
-  app."
+  id="get-started"
+  description="Let an agent build it, or build it by hand to see every
+  file."
 >
   <Card
-    title="Get Started (Claude Code)"
-    to="/full_stack_apps/get_started_claude_code"
+    title="Build with Claude Code"
+    to="/get_started/claude_code"
     icon={<ClaudeLogo />}
   />
   <Card
-    title="Get Started (Codex)"
-    to="/full_stack_apps/get_started_codex"
+    title="Build with Codex"
+    to="/get_started/codex"
     icon={<CodexLogo />}
   />
   <Card
-    title="Get Started (Python)"
-    to="/full_stack_apps/python"
-    icon={<PythonLogo />}
+    title="Build it by hand"
+    to="/get_started/python"
+    description="A Python backend, step by step, to see every file."
   />
   <Card
-    title="Get Started (TypeScript)"
-    icon={<TSLogo />}
-    to="/full_stack_apps/typescript"
+    title="Examples"
+    to="/get_started/examples"
+    description="Complete applications to run and take apart."
   />
 </CardSection>
 
-### Inside an AI chat
+## One app to serve every user — human or machine
+
+You and your agents can build any kind of app with Reboot. One
+backend, one identity per person, and as many front doors as you
+need:
 
 <CardSection
-  id="ai-chat-apps"
-  description="Visual, interactive apps that run inside AI chat
-  interfaces like ChatGPT, Claude, and VS Code."
+  id="surfaces"
+  description="Humans reach your app through a browser, a phone, or a
+  chat client. Agents reach it over MCP. Other services reach it over
+  HTTP."
 >
   <Card
-    title="What is an AI Chat App?"
-    to="/ai_chat_apps/what_is"
+    title="Web apps"
+    to="/surfaces/web"
+    description="A reactive React app on its own origin."
   />
   <Card
-    title="Get Started (Claude Code)"
-    to="/ai_chat_apps/get_started_claude_code"
-    icon={<ClaudeLogo />}
+    title="React Native apps"
+    to="/surfaces/react_native"
+    description="The same hooks and the same backend, on a phone."
+    tag={{
+      label: "Alpha",
+      color: "#c2410c",
+      description: "React Native support is in alpha.",
+    }}
   />
   <Card
-    title="Get Started (Codex)"
-    to="/ai_chat_apps/get_started_codex"
-    icon={<CodexLogo />}
+    title="AI chat apps"
+    to="/surfaces/ai_chat"
+    description="Tools and interactive UIs inside ChatGPT, Claude,
+    and VS Code."
   />
   <Card
-    title="Get Started (Python)"
-    to="/ai_chat_apps/get_started"
-    icon={<PythonLogo />}
+    title="Agents inside your app"
+    to="/agents"
+    description="Durable, replay-safe model and tool calls in a
+    workflow."
   />
 </CardSection>
 
-### Examples
+## Learn the essentials
 
 <CardSection
-  id="examples"
-  description="A variety of examples demonstrating Reboot in action."
+  id="essentials"
+  description="The pages to read once, in order."
 >
   <Card
-    title="Full-stack Examples"
-    to="/full_stack_apps/examples"
+    title="How Reboot works"
+    to="/concepts"
+    description="Durable data structures, method kinds, and the
+    guarantees behind them."
+  />
+  <Card
+    title="Users and sign-in"
+    to="/users/overview"
+    description="Every app's entry point: the auto-constructed
+    User."
+  />
+  <Card
+    title="Define your API"
+    to="/define/overview"
+    description="Declare your state types and their methods."
   />
   <Card
-    title="AI Chat App Examples"
-    to="/ai_chat_apps/examples"
+    title="Implement your API"
+    to="/implement/servicers"
+    description="Write the servicers that back those methods."
+  />
+  <Card
+    title="Call your API"
+    to="/call/overview"
+    description="From React, from your backend, from anywhere
+    else."
   />
 </CardSection>
+
+## Run it anywhere
+
+Reboot is open source. Run a Reboot app on
+[your own infrastructure](/deploy_on_your_own) or on
+[Reboot Cloud](/deploy_on_reboot_cloud) today.
diff --git a/documentation/docs/rbt_cli.md b/documentation/docs/rbt_cli.md
new file mode 100644
index 000000000..b18fb1da4
--- /dev/null
+++ b/documentation/docs/rbt_cli.md
@@ -0,0 +1,85 @@
+# The `rbt` CLI
+
+`rbt` is Reboot's command line tool. It ships with the Reboot library
+rather than being installed separately — see
+[Develop locally](/develop_locally#the-rbt-cli) for how to run it in
+Python and Node.js projects.
+
+Every command reads its flags from an
+[`.rbtrc`](/develop_locally#rbtrc-and-flags) file, so you rarely type
+more than the command itself.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `rbt generate` | Generate server, client, and React code from your API definitions. |
+| `rbt dev run` | Run your application for development, regenerating code and restarting on change. |
+| `rbt dev expunge` | Delete the state a named development application has persisted. |
+| `rbt dashboard` | Serve the developer dashboard, which watches your API directory as you write it. |
+| `rbt inspect type list` | List the state types a running application serves. |
+| `rbt inspect state list` | List the state IDs of one type. |
+| `rbt inspect state get` | Print one instance's state as JSON. |
+| `rbt task list` / `rbt task cancel` | List and cancel an application's [tasks](/tasks). |
+| `rbt export` / `rbt import` | Export application data to, or import it from, JSON-lines files. |
+| `rbt serve run` | Run your application in production on [your own infrastructure](/deploy_on_your_own). |
+| `rbt cloud up` / `rbt cloud down` | Deploy to, or terminate on, [Reboot Cloud](/deploy_on_reboot_cloud). |
+| `rbt cloud logs` | Stream a deployed application's logs. |
+| `rbt cloud secret set` / `list` / `delete` | Manage a deployed application's [secrets](/secrets). |
+
+Add `--help` to any of them for the full flag list.
+
+:::tip Inspecting state
+`rbt inspect` works against a local `rbt dev run` backend and against
+a deployed Reboot Cloud application (via `--application-url` and
+`--admin-credential`). During local development there is also a web
+view at
+[http://localhost:9991/__/inspect](http://localhost:9991/__/inspect).
+:::
+
+## Bring your own certificate with `rbt dev run`
+By default `rbt dev run` backends use plain HTTP, not HTTPS. That is
+convenient, but browsers only use HTTP/2 over TLS, and without HTTP/2
+two limits apply. Every reactive reader holds its own WebSocket, and
+browsers allow only around 200 open WebSockets per page (255 in
+Chrome); beyond that, new ones fail and the Reboot client logs a
+warning. Other calls share a handful of HTTP/1.1 connections per
+host, so many outstanding calls queue behind each other, which the
+client also warns about. Over HTTPS the browser multiplexes all of
+them over one HTTP/2 connection. To enable HTTPS you must provide
+your own TLS certificate when running `rbt dev run`.
+
+### Generating a Certificate with [mkcert](https://github.com/FiloSottile/mkcert)
+
+You can use `mkcert` to issue a certificate. Follow these steps:
+
+* Install `mkcert`: Refer to the instructions in the [`mkcert README`](https://github.com/FiloSottile/mkcert/blob/master/README.md) for installation.
+* Install the root certificate: Run the following command: `mkcert -install`.
+* Issue a certificate: `mkcert localhost`.
+
+:::note
+Running `mkcert <domain>` will issue a certificate for the specified domain. For
+local development, it is recommended to include `localhost` in the certificate's
+Subject Alternative Names. If you use a custom domain, ensure it points to
+`127.0.0.1` in your `/etc/hosts` file for `rbt dev run` to work.
+:::
+
+### Configuring `rbt dev run` with the Certificate
+
+Once the certificate is issued, configure `rbt dev run` with the following flags:
+
+* `--tls-certificate=<path>` - The path to the certificate file (e.g. `localhost.pem`).
+* `--tls-key=<path>` - The path to the key file (e.g. `localhost-key.pem`).
+* `--tls-root-certificate=<path>` - The path to the root certificate file (e.g. `rootCA.pem`).
+  To locate the root certificate, use: `mkcert -CAROOT`.
+
+### Updating Reboot React Endpoint
+
+:::note
+Make sure to update the [`RebootClientProvider's
+url`](https://github.com/reboot-dev/reboot-hello/blob/main/web/src/index.tsx#L16)
+to use HTTPS when using a custom certificate.
+:::
+
+This setup ensures secure local development with custom certificates and enables
+compatibility with `rbt dev run`.
diff --git a/documentation/docs/learn_more/secrets.mdx b/documentation/docs/secrets.mdx
similarity index 98%
rename from documentation/docs/learn_more/secrets.mdx
rename to documentation/docs/secrets.mdx
index 326d14f69..66d133c23 100644
--- a/documentation/docs/learn_more/secrets.mdx
+++ b/documentation/docs/secrets.mdx
@@ -110,7 +110,7 @@ automatic restart so the new values take effect.
 ## Testing with secrets
 
 In tests, set the environment variable before starting the
-[Reboot test harness](/learn_more/testing):
+[Reboot test harness](/testing):
 
 <Tabs groupId="language">
   <TabItem value="python" label="Python">
diff --git a/documentation/docs/learn_more/side_effects.md b/documentation/docs/side_effects.md
similarity index 94%
rename from documentation/docs/learn_more/side_effects.md
rename to documentation/docs/side_effects.md
index 53f727aba..f49f80740 100644
--- a/documentation/docs/learn_more/side_effects.md
+++ b/documentation/docs/side_effects.md
@@ -12,12 +12,12 @@ That's why Reboot makes it easy to safely execute side-effects.
 
 ## Safely executing side-effects
 
-Reboot [methods](/learn_more/define/methods) can be composed
+Reboot [methods](/define/methods) can be composed
 according to a safety hierarchy, which enables simple, safe, and
 powerful APIs.
 
 In order to enable that composition, Reboot methods must:
-1. Isolate any side-effects that they need to execute to [tasks](/learn_more/tasks).
+1. Isolate any side-effects that they need to execute to [tasks](/tasks).
 2. Ensure that the side-effects executed by their tasks are idempotent.
 
 ## Third-party APIs
@@ -30,7 +30,7 @@ contributions of integrations for commonly used APIs!
 ## Validation
 
 In order to validate that side-effects are properly handled, Reboot always executes your
-Reboot [methods](/learn_more/define/methods) twice [^1] when running in development
+Reboot [methods](/define/methods) twice [^1] when running in development
 mode. The second method execution acts as a reminder that all external calls you make in
 Reboot must be able to safely and correctly execute (at least) twice, because in production
 it may be necessary for tasks to rerun in response to temporary failures.
diff --git a/documentation/docs/surfaces/ai_chat.mdx b/documentation/docs/surfaces/ai_chat.mdx
new file mode 100644
index 000000000..b34f7a265
--- /dev/null
+++ b/documentation/docs/surfaces/ai_chat.mdx
@@ -0,0 +1,171 @@
+# AI chat apps
+
+A Reboot application can serve an AI chat client — ChatGPT, Claude,
+VS Code, Goose — as one more front end alongside your
+[web](/surfaces/web) and [React Native](/surfaces/react_native) apps.
+Your methods become tools the AI can call, and your React components
+open **inside the conversation** as interactive UIs.
+
+It is the same backend, the same state, and the same signed-in
+[`User`](/users/overview). Nothing about a chat surface is a separate
+kind of application.
+
+## What you get
+
+- **Show, don't tell.** Instead of a wall of text, the AI opens a real
+  UI: buttons, forms, live data.
+- **React to state changes.** Those UIs update in real time as backend
+  state changes — whether the user, the AI, or another client made the
+  change.
+- **Persist across conversations.** State is durable. Close the chat,
+  come back next week, and everything is still there, under the same
+  `User`.
+
+## How it works
+
+The protocol is [MCP, the Model Context
+Protocol](https://modelcontextprotocol.io) — the open standard AI
+clients use to discover and talk to external servers. An MCP server
+exposes *tools*: actions the AI can call.
+
+You do not write any MCP protocol code: `Application` serves the MCP
+endpoint at `/mcp`. Configure [`oauth=`](/users/oauth) and that
+endpoint requires — and establishes — a signed-in user.
+
+Three things map across:
+
+**Methods become tools.** Any method on any type is exposed as an MCP
+tool when you declare it with `mcp=Tool()`:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&lines=63-88&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
+
+```python
+api = API(
+    User=Type(
+        state=UserState,
+        methods=Methods(
+            create_counter=Transaction(
+                request=CreateCounterRequest,
+                response=CreateCounterResponse,
+                description="Create a new Counter with a "
+                "description of what it counts. Returns "
+                "the `counter_id`, which is not "
+                "human-readable but should be passed to "
+                "future tool calls that need it.",
+                mcp=Tool(),
+            ),
+            list_counters=Reader(
+                request=None,
+                response=ListCountersResponse,
+                description="List all counters created "
+                "by this user. Returns `counter_id` and "
+                "description for each. The `counter_id` "
+                "is not human-readable, but use it when "
+                "calling tools that take a `counter_id`.",
+                mcp=Tool(),
+            ),
+        ),
+    ),
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+**`User` methods need no state ID.** Reboot resolves the right `User`
+from the authenticated caller, so the AI never has to know — or be
+told — who it is acting for. Methods on other types take the
+instance's state ID, which the AI receives when the instance is
+created and passes back on later calls.
+
+**[`UI` methods](/surfaces/ui_methods) become tools that open a React
+component.** When the AI calls one, the chat client displays your
+component inline.
+
+## Users on the chat surface
+
+Chat clients sign in through the same OAuth server as everything else.
+The client discovers it, registers itself, and runs the flow when the
+user connects your app; Reboot then
+[auto-constructs their `User`](/users/overview) exactly as it would
+for a browser.
+
+This is what makes `User` the natural entry point on this surface in
+particular. The AI's memory of a conversation is its context window,
+which does not survive into the next conversation. State IDs it was
+handed — a `counter_id`, an `order_id` — are gone with it. So:
+
+- Record what the user owns in `User` state.
+- Give `User` a `list_…` method with `mcp=Tool()` so the AI can find
+  its way back in a fresh conversation.
+
+Do that, and a user who opened an order last week can say "show me my
+order" today and the AI can actually find it.
+
+## Choosing which methods the AI can call
+
+Every method must declare its MCP exposure explicitly:
+`mcp=Tool()` to expose it, `mcp=None` to hide it. There is no implicit
+default, so nothing is exposed to an AI by accident.
+
+Not every method should be a tool:
+
+1. **Human-only actions.** Some things should only happen when a
+   person clicks — a "Yes, confirm" button in a UI. Give that method
+   `mcp=None`: the human's click still calls it, the AI cannot.
+2. **Context bloat.** Every tool you expose is added to the AI's
+   context window. Too many tools makes the model worse at choosing
+   among them.
+
+`Tool()` takes optional overrides:
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `str` or `None` | Custom tool name; defaults to the method name. |
+| `title` | `str` or `None` | Human-readable title; defaults to the method name. |
+
+The method's `description` is what the AI reads to decide when and how
+to call it, so write it as instructions to the AI, not as a comment to
+your colleagues. See
+[Creating tools](/define/pydantic#creating-tools-for-the-ai).
+
+## Presenting your app
+
+`Application` takes three fields that a chat client shows to users:
+
+```python
+Application(
+    title="Chat Counter",
+    description=(
+        "Lets a chat client create, list, increment, and show "
+        "counters on your behalf."
+    ),
+    example_prompts=example_prompts,
+    servicers=[UserServicer, CounterServicer],
+    oauth=OAuth(...),
+)
+```
+
+`example_prompts` are rendered as copyable cards by the setup wizard
+your app serves at its root URL, giving a first-time visitor something
+to try.
+
+## Connecting a client
+
+Your app serves a **setup wizard** at its root URL — `http://localhost:9991`
+under `rbt dev run`, or the public URL of a deployed app. It walks you
+through connecting the chat client of your choice, including the public
+tunnel that cloud-hosted clients need to reach a development machine,
+and confirms once the first request arrives.
+
+For the same steps written out, see
+[From an MCP client](/call/from_mcp_client).
+
+## Next
+
+- [`UI` methods](/surfaces/ui_methods) — React components rendered in
+  the conversation.
+- [Define your API](/define/pydantic) — declaring types, methods, and
+  tools.
+- [From an MCP client](/call/from_mcp_client) — connecting Claude,
+  ChatGPT, and inspectors.
+- [Users and sign-in](/users/overview) — the `User` the AI acts for.
diff --git a/documentation/docs/surfaces/overview.mdx b/documentation/docs/surfaces/overview.mdx
new file mode 100644
index 000000000..ad8fc55c5
--- /dev/null
+++ b/documentation/docs/surfaces/overview.mdx
@@ -0,0 +1,121 @@
+# One backend, many frontends
+
+One app to serve every user — human or machine. A Reboot backend does
+not know or care what kind of client is calling it: the same types,
+the same methods, and the same durable state are reachable from every
+front door.
+
+## Humans
+
+| Surface | What it is | Start here |
+| --- | --- | --- |
+| **Web** | A React app in the browser, talking to your Reboot backend. | [Web apps](/surfaces/web) |
+| **React Native** | A React Native app on iOS and Android, using the same generated hooks as the web app. In alpha. | [React Native apps](/surfaces/react_native) |
+| **AI chat** | Your methods as MCP tools, and React components rendered in the conversation as MCP Apps, inside ChatGPT, Claude, or VS Code. | [AI chat apps](/surfaces/ai_chat) |
+
+## Agents
+
+An AI agent reaches your app over [MCP](/surfaces/ai_chat). Every
+method, `User` methods included, says whether it is a tool:
+`mcp=Tool()` exposes it to the agent, `mcp=None` keeps it out of
+reach.
+
+An agent can also run *inside* your app, rather than calling in from
+outside: see [Agents](/agents) for Pydantic AI agents whose model and
+tool calls are durable and replay-safe inside a
+[workflow](/implement/workflows).
+
+## Services
+
+Another service, a script, or your own backend code calls your
+application directly — see
+[from within your app](/call/from_within_your_app),
+[from outside your app](/call/from_outside_your_app), and
+[over HTTP](/call/via_http). You can also add
+[custom HTTP routes](/implement/application#http-custom-routes) for
+webhooks and anything else that cannot call a method.
+
+## What stays the same
+
+Whichever front door a call comes through, three things do not change.
+
+**One identity per user.** [Sign-in](/users/overview) is handled by
+the backend's OAuth server, not by any one client. A person who signs
+in on the web is the same `User`, with the same state, in your mobile
+app and in their chat client. There is no account linking to build.
+
+**One set of generated hooks, and one way in.** `rbt generate
+--react=<dir>` emits one typed React client that the web app, the
+native app, and any [`UI` methods](/surfaces/ui_methods) all import
+from. On the client, sign-in is just `useSignIn()` — on the web and in
+a native app; a chat client signs the person in before any `UI` loads
+— and the generated `useUser()`, which resolves the caller's own
+`User`:
+
+```tsx
+const Root = () => {
+  const { user, isLoading } = useUser();
+  if (isLoading || user === undefined) return <SignIn />;
+  return <TodoLists user={user} />;
+};
+
+const TodoLists = ({ user }: { user: UseUserApi }) => {
+  const { response } = user.useListTodoLists();
+  return (
+    <ul>
+      {(response?.todoLists ?? []).map((todoList) => (
+        <li key={todoList.todoListId}>{todoList.title}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+See [On the client](/users/overview#on-the-client) for the whole
+pattern.
+
+**One authorization model.** [Authorizers](/users/authorization) run
+on the backend, so a method restricted to its owner is restricted the
+same way whether the caller is a browser, a phone, an AI, or another
+service.
+
+## What differs
+
+Only the mechanics at the very edge:
+
+- **Where the backend URL comes from.** The web app reads it from an
+  environment variable at build time; a native app reads it from its
+  own config; a `UI` method needs no URL at all, because the provider
+  detects the chat host.
+- **How the sign-in flow runs.** A browser redirects and comes back. A
+  native app opens a system browser. A chat client runs the flow when
+  the user connects your app.
+- **What the user sees.** A full page, a native screen, or a component
+  embedded in a conversation.
+
+## Serving several at once
+
+Nothing stops one application from doing all of it. The
+[`bank-pydantic`](https://github.com/reboot-dev/reboot-bank-pydantic)
+example (described under [Examples](/get_started/examples#bank-pydantic))
+does: one backend, one `User` type, and three front ends that all
+import the same generated client.
+
+| Front end | In the example | Docs |
+| --- | --- | --- |
+| Browser app | `frontend/web/` | [Web apps](/surfaces/web) |
+| React Native (Expo) app | `frontend/mobile/` | [React Native apps](/surfaces/react_native) |
+| MCP UIs, one directory per `UI` method | `frontend/mcp/` | [`UI` methods](/surfaces/ui_methods) |
+| Generated client, shared by all three | `frontend/api/` | [Call your API from React](/call/from_react) |
+
+That is the layout worth copying when you expect more than one
+surface.
+
+## Next
+
+- [Web apps](/surfaces/web)
+- [React Native apps](/surfaces/react_native)
+- [AI chat apps](/surfaces/ai_chat)
+- [Agents](/agents) — an agent running inside your app.
+- [Call your API from React](/call/from_react) — the hooks reference
+  shared by all of them.
diff --git a/documentation/docs/surfaces/react_native.mdx b/documentation/docs/surfaces/react_native.mdx
new file mode 100644
index 000000000..d040559b9
--- /dev/null
+++ b/documentation/docs/surfaces/react_native.mdx
@@ -0,0 +1,215 @@
+# React Native apps
+
+:::warning[React Native support is in alpha]
+
+The client runs on iOS and Android, and the
+[`bank-pydantic`](https://github.com/reboot-dev/reboot-bank-pydantic)
+example ships a complete Expo app, but it has had far less use than the web
+client, and the [agent skills](/get_started/claude_code) do not
+scaffold a native app yet. Expect rough edges, and please report them
+on [Discord](https://discord.gg/cRbdcS94Nr) or
+[GitHub](https://github.com/reboot-dev/reboot/issues).
+
+:::
+
+The Reboot React client runs in React Native, on iOS and Android, as
+well as in the browser. Your components, your generated hooks, and
+your reactive reads are the same code you would write for the
+[web](/surfaces/web).
+
+One thing genuinely differs: signing in. A native app cannot use the
+browser's redirect flow, so Reboot's OAuth server also speaks the flow
+native apps use, and the result is the same signed-in `User`.
+
+## Install
+
+```sh
+npm install -S @reboot-dev/reboot-react
+```
+
+An Expo app additionally needs the three modules Reboot delegates to:
+
+```sh
+npx expo install expo-web-browser expo-secure-store expo-linking
+npx expo install react-native-get-random-values
+```
+
+Register the last one before anything else loads: Reboot needs
+`crypto.getRandomValues` at import time, and React Native's runtime
+does not provide it:
+
+```js
+// index.js
+import "react-native-get-random-values";
+
+import { registerRootComponent } from "expo";
+import App from "./src/App";
+
+registerRootComponent(App);
+```
+
+On web that import is a no-op, since browsers already have Web Crypto.
+
+## Sign-in with `expoAuth`
+
+Build an auth object and hand it to `RebootClientProvider` as
+`nativeAuth`. Everything above the provider is written exactly as it
+is for the web.
+
+```tsx
+import { RebootClientProvider } from "@reboot-dev/reboot-react";
+import { expoAuth } from "@reboot-dev/reboot-react/native";
+import * as Linking from "expo-linking";
+import * as SecureStore from "expo-secure-store";
+import * as WebBrowser from "expo-web-browser";
+
+// Built once at module scope, not inline in the JSX: the provider
+// rebuilds its session machinery whenever this value changes
+// identity.
+const auth = expoAuth({
+  WebBrowser,
+  SecureStore,
+  Linking,
+  clientName: "Rebank Mobile",
+});
+
+const App = () => (
+  <RebootClientProvider url={REBOOT_URL} nativeAuth={auth}>
+    <Root />
+  </RebootClientProvider>
+);
+```
+
+`expoAuth` needs three things from Expo, and nothing else:
+
+| Module | What Reboot uses it for |
+| --- | --- |
+| `expo-web-browser` | Opening the identity provider's page in a system browser and detecting the redirect back. |
+| `expo-secure-store` | Keeping the refresh token and this installation's client registration in the device keychain. |
+| `expo-linking` | Deriving the redirect URI from the `scheme` in `app.json`. |
+
+`ExpoAuthOptions` also takes `redirectPath` (default `"redirect"`,
+giving `myapp://redirect`), `clientName` (shown on the consent screen,
+when there is one), and `storageKeyPrefix` (so two Reboot apps on one
+device do not overwrite each other's session).
+
+Reboot itself takes no dependency on Expo — the modules are typed
+structurally and passed in.
+
+### Bare React Native
+
+If you are not using Expo, use `nativeAuth` directly and supply the
+two primitives yourself:
+
+```ts
+import { nativeAuth } from "@reboot-dev/reboot-react/native";
+
+const auth = nativeAuth({
+  redirectUri: "myapp://redirect",
+  openAuthSession: myOpenAuthSession,  // Open a URL; resolve on redirect.
+  storage: myKeychainStorage,          // getItemAsync/setItemAsync/deleteItemAsync.
+});
+```
+
+The whole OAuth protocol lives inside Reboot; only opening a browser
+tab and persisting a secret are passed in.
+
+## Then it is the same as the web
+
+```tsx
+const Root = () => {
+  const signIn = useSignIn();
+  const signOut = useSignOut();
+  // No id is passed: the signed-in user's own `User` is this state
+  // type's default, resolved from the backend.
+  const { user, isLoading } = useUser();
+
+  if (isLoading) return <Notice text="Checking session…" />;
+  if (user === undefined) return <SignIn onSignIn={() => signIn()} />;
+  return <BankInterface user={user} onSignOut={() => void signOut()} />;
+};
+```
+
+The same [`useSignIn()`, `useSignOut()`, and generated
+`useUser()`](/surfaces/web#signing-in) hooks, against the same OAuth
+server, resolving the same `User`. `returnTo` is ignored on native,
+because there is no page to come back to.
+
+## Skip the consent screen
+
+A native app registers itself with the OAuth server dynamically, and
+registration proves nothing about who is registering — so by default
+Reboot shows the user a [consent
+screen](/users/oauth#skip_consent_for_redirect_uris) naming the client
+and the redirect URI its tokens will go to.
+
+List your own app's redirect URI to skip it:
+
+```python
+oauth=OAuth(
+    provider=...,
+    allowed_origins=[...],
+    skip_consent_for_redirect_uris=["bankpydanticmobile://redirect"],
+)
+```
+
+The URI comes from your `app.json` `scheme` plus the `redirectPath`.
+Under `rbt dev run`, Expo Go's `exp://<host>/--/...` development URI
+skips consent automatically — its host and port change from machine to
+machine, so there is no stable spelling to list — which means
+`npm start` needs no configuration at all.
+
+:::tip Prefer a verified link in production
+A custom scheme can be claimed by another app on the same device. An
+`https://` App Link or Universal Link, which the operating system
+verifies against your domain, cannot.
+:::
+
+## Pointing at the backend
+
+A simulator can reach `http://localhost:9991`; a physical phone
+cannot. Read the URL from the environment and set it per target:
+
+```tsx
+const REBOOT_URL =
+  process.env.EXPO_PUBLIC_REBOOT_URL ?? "http://localhost:9991";
+```
+
+| Target | `EXPO_PUBLIC_REBOOT_URL` |
+| --- | --- |
+| Browser (`expo start --web`) or iOS simulator | Unset — `localhost` works. |
+| Android emulator | `http://10.0.2.2:9991` |
+| Physical device on the same Wi-Fi | `http://<your-LAN-IP>:9991` |
+
+`rbt dev run` binds all interfaces, so it is reachable from a
+simulator and from a phone on the same network without extra flags.
+
+## Sharing generated code with a web app
+
+Point `rbt generate` at a directory both front ends can import from:
+
+```
+generate --react=frontend/api
+```
+
+Metro (React Native's bundler) resolves imports without file
+extensions, so leave `--react-extensions` off; the generated client's
+relative imports then resolve under both Vite and Metro.
+
+## Compatibility notes
+
+React Native does not provide every web API the client relies on. Two
+things are yours to cover, both shown above:
+
+- **`crypto.getRandomValues`** — import
+  `react-native-get-random-values` first, in `index.js`.
+- **Streaming `fetch` responses**, which reactive readers need. Use
+  Expo SDK 52 or newer, whose `fetch` supports them.
+
+## A complete example
+
+The [`bank-pydantic`](https://github.com/reboot-dev/reboot-bank-pydantic)
+example ships a full Expo front end under
+[`frontend/mobile/`](https://github.com/reboot-dev/reboot-bank-pydantic/tree/main/frontend/mobile),
+alongside a browser SPA and MCP UIs — all three against one backend
+and one `User`. See [Examples](/get_started/examples#bank-pydantic).
diff --git a/documentation/docs/learn_more/implement/ui_methods.mdx b/documentation/docs/surfaces/ui_methods.mdx
similarity index 84%
rename from documentation/docs/learn_more/implement/ui_methods.mdx
rename to documentation/docs/surfaces/ui_methods.mdx
index 47eea388e..aff579adc 100644
--- a/documentation/docs/learn_more/implement/ui_methods.mdx
+++ b/documentation/docs/surfaces/ui_methods.mdx
@@ -1,25 +1,28 @@
-# UIs for AI Chat Apps
-
-UI methods declare a React component that opens in the AI chat
-interface when the AI calls the associated tool. Unlike `reader`,
-`writer`, `transaction`, and `workflow` methods, UI methods have
-no backend servicer code — the React `App.tsx` component **is**
-the implementation.
-
-:::info MCP only
-UI methods are only callable over [MCP](/learn_more/mcp_apps) —
-they appear as tools in AI chat interfaces. There is no way to
-invoke a `UI` method from a browser or backend.
+# UI methods
+
+A `UI` method declares a React component that an
+[AI chat client](/surfaces/ai_chat) opens inside the conversation when
+the AI calls the associated tool. Unlike `reader`, `writer`,
+`transaction`, and `workflow` methods, a `UI` method has no backend
+servicer code — the React `App.tsx` component **is** the
+implementation.
+
+:::info The AI chat surface only
+`UI` methods exist for [MCP](/surfaces/ai_chat), where they appear as
+tools. There is no way to invoke one from a browser or from your
+backend. Your [web](/surfaces/web) and
+[React Native](/surfaces/react_native) frontends render their own
+components and call ordinary methods.
 :::
 
 ## Syntax
 
 You declare a `UI` method in your
-[API definition](/learn_more/define/pydantic), alongside your
+[API definition](/define/pydantic), alongside your
 other methods:
 
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py&lines=88-94&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py -->
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py&lines=88-94&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py -->
 
 ```python
 show_clicker=UI(
@@ -48,8 +51,8 @@ show_clicker=UI(
 
 From the `ai-chat-counter` example:
 
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&lines=92-98&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py&lines=92-98&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/api/ai_chat_counter/v1/counter.py -->
 
 ```python
 show_clicker=UI(
@@ -67,8 +70,8 @@ show_clicker=UI(
 
 From the `ai-chat-counter-dashboard` example:
 
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py&lines=95-102&syntax=python) -->
-<!-- The below code snippet is automatically added from ../../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py -->
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py&lines=95-102&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter-dashboard/api/ai_chat_counter/v1/counter.py -->
 
 ```python
 show_dashboard=UI(
@@ -160,7 +163,7 @@ const Clicker: React.FC<{ counter: UseCounterApi }> = ({ counter }) => {
 };
 ```
 
-## How it works under the hood
+## How it works
 
 When you define a `UI` method, Reboot generates two MCP
 artifacts:
@@ -171,9 +174,9 @@ artifacts:
 2. **An MCP resource** that serves the compiled HTML/JS/CSS. The
    AI client loads this resource in an embedded browser.
 
-The React app communicates with your Reboot backend via
-WebSocket subscriptions (for reads) and the appropriate write
-channel (for mutations).
+The React app talks to your backend through the same
+[generated hooks](/call/from_react) as any other front end, so its
+reads are reactive and its mutations retry safely.
 
 ## Bundling UI methods
 
@@ -184,6 +187,11 @@ file so that the Reboot server can serve it as an MCP resource.
 Use [Vite](https://vite.dev/) with
 [`vite-plugin-singlefile`](https://www.npmjs.com/package/vite-plugin-singlefile).
 
+The [agent skills](/get_started/claude_code) write the
+`vite.config.ts` and `build.mjs` below for you. If you are setting a
+project up by hand, copy them from an example such as
+[`bank-pydantic`](https://github.com/reboot-dev/reboot-bank-pydantic/tree/main/frontend).
+
 ### Dependencies
 
 ```sh
@@ -192,14 +200,20 @@ npm install -D @vitejs/plugin-react vite vite-plugin-singlefile
 
 ### Vite configuration
 
-Create a `vite.config.ts`. One config drives three jobs: the dev
-server, and two builds selected by the `RBT_BUILD_TARGET` env var (set
-per UI by `build.mjs`) — a per-UI MCP build
-(`RBT_BUILD_TARGET=mcp:<name>`) and the standalone `web/` SPA build
-(`RBT_BUILD_TARGET=web`). It auto-discovers MCP UIs from the `mcp/`
-directory (each subdirectory with an `index.html`):
+One `vite.config.ts` drives three jobs: the dev server, and two
+builds selected by the `RBT_BUILD_TARGET` env var (set per UI by
+`build.mjs`) — a per-UI MCP build (`RBT_BUILD_TARGET=mcp:<name>`) and
+the standalone `web/` SPA build (`RBT_BUILD_TARGET=web`). It
+auto-discovers MCP UIs from the `mcp/` directory (each subdirectory
+with an `index.html`).
+
+<details>
+<summary>The full <code>frontend/vite.config.ts</code></summary>
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/frontend/vite.config.ts&syntax=typescript) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/frontend/vite.config.ts -->
 
-```ts title=frontend/vite.config.ts
+```typescript
 // Vite configuration for Reboot UIs.
 //
 // One config drives three jobs. The dev server is selected by
@@ -433,6 +447,10 @@ export default defineConfig(({ command }) => {
 });
 ```
 
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+</details>
+
 ### Building
 
 Build one UI by name by setting `RBT_BUILD_TARGET` (or build every UI and
diff --git a/documentation/docs/surfaces/web.mdx b/documentation/docs/surfaces/web.mdx
new file mode 100644
index 000000000..c16168c66
--- /dev/null
+++ b/documentation/docs/surfaces/web.mdx
@@ -0,0 +1,233 @@
+# Web apps
+
+A Reboot web app is an ordinary React single-page app. What Reboot
+adds is that it talks to your backend through generated, typed hooks
+that are *reactive* — React components re-render when backend state
+changes, without polling — and that its users sign in through your
+backend's own OAuth server.
+
+This page covers how a web front end is put together. For the full hooks
+reference, see [Call your API from React](/call/from_react).
+
+## Install and generate
+
+Add the React client to your front end's `package.json`:
+
+```sh
+npm install -S @reboot-dev/reboot-react
+```
+
+Tell `rbt generate` where to emit the typed client, in your
+[`.rbtrc`](/develop_locally#rbtrc-and-flags):
+
+```
+generate --react=frontend/api
+```
+
+Generating into `frontend/api/` — a sibling of the app itself — means
+every front end of your application (web, mobile, MCP UIs) shares one
+client. Keep your bundler's root at `frontend/` so that directory is
+inside it; if your app root is `frontend/web/` instead, Vite needs
+`server.fs.allow: [".."]` to read a sibling.
+
+## Point the client at your backend
+
+Wrap your app in a `RebootClientProvider` with the backend's URL:
+
+```tsx
+// frontend/web/src/main.tsx
+import { RebootClientProvider } from "@reboot-dev/reboot-react";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <RebootClientProvider url={import.meta.env.VITE_REBOOT_URL}>
+      <Root />
+    </RebootClientProvider>
+  </StrictMode>
+);
+```
+
+Read the URL from the environment rather than hard-coding it. A web
+app is served from its own origin — a CDN or static host — almost
+never the same origin as the backend, so a real deployment *must* set
+it:
+
+```
+# frontend/web/.env.development
+VITE_REBOOT_URL="http://localhost:9991"
+```
+
+```
+# frontend/web/.env.production
+VITE_REBOOT_URL="https://your-backend-host.example.com"
+```
+
+## Signing in
+
+Reboot's OAuth server does the work; your app needs three hooks.
+
+```tsx
+import { useUser } from "@api/todos/v1/todos_rbt_react";
+import { useSignIn, useSignOut } from "@reboot-dev/reboot-react";
+
+export const Root = () => {
+  const { user, isLoading } = useUser();
+  const signIn = useSignIn();
+  const signOut = useSignOut();
+
+  // The provider renders immediately and resolves the session in the
+  // background, so `isLoading` holds until it lands.
+  if (isLoading) {
+    return <p>Checking session…</p>;
+  }
+
+  if (user === undefined) {
+    return <button onClick={() => signIn()}>Sign in</button>;
+  }
+
+  return <App user={user} onSignOut={() => void signOut()} />;
+};
+```
+
+- **`useSignIn()`** returns a function that starts the sign-in flow.
+  The browser goes to your identity provider and comes back signed
+  in, to where the user was. Pass a `returnTo` to send them somewhere
+  else.
+- **`useSignOut()`** drops this device's session. The identity
+  provider's own session is left alone.
+- **`useUser()`** is *generated from your `User` type*, so it is typed
+  to your API. Called with no ID it resolves the signed-in user's own
+  `User` — the instance Reboot
+  [auto-constructed](/users/overview) at sign-in. `user` is
+  `undefined` when nobody is signed in.
+
+The `user` handle exposes your `User` methods: reads as nested hooks,
+mutations as plain calls.
+
+```tsx
+const { response } = user.useListTodoLists();
+await user.createTodoList({ title: "Groceries" });
+```
+
+:::tip Check `isLoading` first
+While `isLoading` is `true`, `user` is still `undefined`. Reaching the
+`undefined` check after loading has finished is what genuinely means
+"nobody is signed in".
+:::
+
+### Other state types
+
+Generated hooks exist for every state type, not just `User`:
+
+```tsx
+const todoList = useTodoList({ id: todoListId });
+const { response } = todoList.useTodos();
+await todoList.add({ todo: "Milk" });
+```
+
+Where does `todoListId` come from? From the person's `User`, the one
+instance you can reach without an ID: it records what they own, and a
+component reads those IDs off it and passes each one down.
+
+```tsx
+const TodoLists = ({ user }: { user: UseUserApi }) => {
+  const { response } = user.useListTodoLists();
+  return (response?.todoLists ?? []).map((todoList) => (
+    <TodoListView key={todoList.todoListId} id={todoList.todoListId} />
+  ));
+};
+
+const TodoListView = ({ id }: { id: string }) => {
+  const todoList = useTodoList({ id });
+  const { response } = todoList.useTodos();
+  return (
+    <ul>
+      {(response?.todos ?? []).map((todo) => (
+        <li key={todo}>{todo}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+## Backend configuration
+
+Two things on the backend matter to a web front end.
+
+**1. `allowed_origins`.** Your SPA is on a different origin than the
+backend, so it must be allow-listed for credentialed requests:
+
+```python
+oauth=OAuth(
+    provider=...,
+    allowed_origins=["https://app.example.com"],
+)
+```
+
+In development, `http://localhost` and `http://127.0.0.1` on any port
+are allowed automatically. In production, omitting `allowed_origins`
+is a startup error. See [Configure OAuth](/users/oauth#allowed_origins).
+
+**2. The callback URL.** Register
+`<your-backend-url>/__/oauth/callback` with your identity provider —
+the backend's URL, not the SPA's.
+
+## Local development
+
+Run two processes: the backend, and the Vite dev server.
+
+```sh
+rbt dev run
+```
+
+```sh
+cd frontend && npm run dev
+```
+
+`rbt dev run` generates the React client before it starts, so the dev
+server always has an up-to-date `frontend/api/`.
+
+If you want Reboot to serve the front end too — so both are on one
+origin, and so `UI` methods work — point it at your frontend root in
+`.rbtrc`:
+
+```
+# The frontend root, shared by the `:hmr` and `:dist` configs below.
+dev run --frontend-root-path=frontend
+
+# HMR: proxy `/__/frontend/**` to the Vite dev server.
+dev run:hmr --frontend-host=http://localhost:4444
+dev run --default-config=hmr
+
+# Dist: serve pre-built assets instead. `rbt dev run --config=dist`.
+dev run:dist --frontend-dist-path=frontend/dist
+```
+
+See [Develop locally](/develop_locally#frontend-flags) for what each
+flag does.
+
+## Going to production
+
+1. Build the SPA (`npm run build`) and publish it to any static host.
+2. Set `VITE_REBOOT_URL` to the backend's public origin at build time.
+3. Deploy the backend — [Reboot Cloud](/deploy_on_reboot_cloud) or
+   [your own infrastructure](/deploy_on_your_own).
+4. Add the SPA's origin to `allowed_origins`, and the backend's
+   public URL plus `/__/oauth/callback` to your identity provider.
+
+:::tip Use TLS
+Browsers only use HTTP/2 over TLS. Over plain HTTP, every reactive
+reader holds its own WebSocket, and browsers allow only around 200
+of those per page (255 in Chrome), so an app with many concurrent
+readers needs HTTPS.
+See [the `rbt` CLI](/rbt_cli#bring-your-own-certificate-with-rbt-dev-run)
+for local certificates.
+:::
+
+## Next
+
+- [Call your API from React](/call/from_react) — reactive reads,
+  optimistic updates, offline caching, Next.js server components.
+- [Users and sign-in](/users/overview) — what `useUser()` is resolving.
+- [React Native apps](/surfaces/react_native) — the same code on a
+  phone (alpha).
diff --git a/documentation/docs/learn_more/tasks.mdx b/documentation/docs/tasks.mdx
similarity index 79%
rename from documentation/docs/learn_more/tasks.mdx
rename to documentation/docs/tasks.mdx
index 43d543ef0..af8f8c135 100644
--- a/documentation/docs/learn_more/tasks.mdx
+++ b/documentation/docs/tasks.mdx
@@ -9,15 +9,15 @@ are typically used for long-running operations, operations whose execution
 should be deferred to a later time, and/or operations that perform side effects
 external to Reboot.
 
-Any Reboot [method](/learn_more/define/methods) can be invoked as a task by using
+Any Reboot [method](/define/methods) can be invoked as a task by using
 `schedule()` or `spawn()`, followed by a call to the method.
 
 ## Scheduling and Spawning
 
 ### `schedule()`
 
-`schedule()` can be used from within a [`writer`](/learn_more/define/methods#kinds) or
-[`transaction`](/learn_more/define/methods#kinds) method. It returns the ID of a
+`schedule()` can be used from within a [`writer`](/define/methods#kinds) or
+[`transaction`](/define/methods#kinds) method. It returns the ID of a
 task that hasn't been started yet. This is because the creation of a task is an
 _effect_, and effects only occur after the method that invokes `schedule()`
 completes. (If the method's execution fails at any point, its scheduled tasks
@@ -33,8 +33,8 @@ Here's an example:
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/bank/backend/src/account_servicer.py&lines=38-38) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/src/account_servicer.py -->
+(CODE:src=../../reboot/examples/monorepo/bank/backend/src/account_servicer.py&lines=38-38) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/monorepo/bank/backend/src/account_servicer.py -->
 
 ```py
 task_id = await self.ref().schedule().welcome_email(context)
@@ -44,8 +44,8 @@ task_id = await self.ref().schedule().welcome_email(context)
   </TabItem>
   <TabItem value="typescript" label="TypeScript">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts&lines=21-21) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts -->
+(CODE:src=../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts&lines=21-21) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/bank-nodejs/backend/src/account_servicer.ts -->
 
 ```ts
 const taskId = await this.ref().schedule().welcomeEmail(context);
@@ -59,9 +59,9 @@ const taskId = await this.ref().schedule().welcomeEmail(context);
 
 ### `spawn()`
 
-`spawn()` can be used from within a [`workflow`](/learn_more/define/methods#kinds)
+`spawn()` can be used from within a [`workflow`](/define/methods#kinds)
 method; it can also be invoked from [outside
-Reboot](/learn_more/call/from_outside_your_app) using an
+Reboot](/call/from_outside_your_app) using an
 `ExternalContext`. Calling `spawn()` returns a `[MethodName]Task` object that
 represents the running task. You can use `await` on the task object to get the
 response (i.e., the return value of the method executed by the task).
@@ -90,13 +90,13 @@ const response = await task;
 
 Reboot automatically manages the execution of tasks. If a task encounters an
 unexpected error, Reboot will re-execute the task until it either completes
-successfully or [aborts with a declared error](/learn_more/errors).  As a result,
+successfully or [aborts with a declared error](/errors).  As a result,
 task methods should be designed to behave correctly even if they are executed
 multiple times. For example, if a task performs side-effects outside of Reboot,
 the developer should decide whether the side-effect should be re-executed every
 time the task is run ("at least once"), or only the first time ("at most
 once"). Reboot provides several helpers to facilitate this; see the [workflow
-documentation](/learn_more/implement/workflows) for more detail.
+documentation](/implement/workflows) for more detail.
 
 ## Running a task at a specific time in the future
 
@@ -116,8 +116,8 @@ available to handle the request.
 <Tabs groupId="language">
   <TabItem value="python" label="Python" default>
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/boutique/backend/src/shipping/servicer.py&lines=30-35) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/boutique/backend/src/shipping/servicer.py -->
+(CODE:src=../../reboot/examples/boutique/backend/src/shipping/servicer.py&lines=30-35) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/boutique/backend/src/shipping/servicer.py -->
 
 ```py
 await self.ref().schedule(
@@ -155,8 +155,8 @@ If all you have is a `TaskId`, you can use `retrieve()` to get a
 <Tabs groupId="language">
   <TabItem value="python" label="Python">
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py&lines=89-92) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py -->
+(CODE:src=../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py&lines=89-92) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/monorepo/bank/backend/tests/account_servicer_test.py -->
 
 ```py
 response = await Account.WelcomeEmailTask.retrieve(
@@ -179,7 +179,7 @@ const response = await Account.WelcomeEmailTask.retrieve(context, { taskId });
 
 If a task encounters an unexpected error, it will be retried until it
 eventually runs to completion.
-[Learn more about expected and unexpected errors](/learn_more/errors).
+[Learn more about expected and unexpected errors](/errors).
 
 Tasks that are failing to complete due to errors can be "hotfixed" by deploying
 a new version of the app. The next time the task runs, it will use the fixed
diff --git a/documentation/docs/learn_more/testing.md b/documentation/docs/testing.md
similarity index 69%
rename from documentation/docs/learn_more/testing.md
rename to documentation/docs/testing.md
index cfc3ad4cf..b9f137db3 100644
--- a/documentation/docs/learn_more/testing.md
+++ b/documentation/docs/testing.md
@@ -12,8 +12,8 @@ you to start your servicer, create a context, and call the method you want to
 test.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/chat-room/backend/tests/chat_room_servicer_test.py&lines=10-40) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room/backend/tests/chat_room_servicer_test.py -->
+(CODE:src=../../reboot/examples/chat-room/backend/tests/chat_room_servicer_test.py&lines=10-40) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/chat-room/backend/tests/chat_room_servicer_test.py -->
 
 ```py
 async def asyncSetUp(self) -> None:
@@ -52,13 +52,13 @@ async def test_chat_room(self) -> None:
 
 #### Setting Secrets
 
-Some servicers may use [secrets](/learn_more/secrets) for connecting
+Some servicers may use [secrets](/secrets) for connecting
 to external services or handling sensitive data. In tests, set the
 required environment variables before starting the test harness.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/boutique/backend/tests/full_app_test.py&lines=25-25) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/boutique/backend/tests/full_app_test.py -->
+(CODE:src=../../reboot/examples/boutique/backend/tests/full_app_test.py&lines=25-25) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/boutique/backend/tests/full_app_test.py -->
 
 ```py
 os.environ["MAILGUN_API_KEY"] = MAILGUN_API_KEY
@@ -93,8 +93,8 @@ Committed state surviving a restart is Reboot's own guarantee, so a
 test that only asserts "the data is still there" afterwards is
 testing Reboot rather than your application. What's worth testing is
 what your app had **in flight** when the process died — a
-[task](/learn_more/tasks) half-run, a
-[workflow](/learn_more/implement/workflows) between steps, an effect
+[task](/tasks) half-run, a
+[workflow](/implement/workflows) between steps, an effect
 that must happen exactly once — and the invariants a partial
 recovery could break: a counter that must not double-count, a
 payment that must not go out twice.
@@ -109,7 +109,7 @@ A few rules the harness enforces:
   harness itself — your `asyncTearDown` still calls `stop()`.
 * While the app is down, don't `await` a unary call from the test's
   context. An
-  [`ExternalContext`](/learn_more/call/from_outside_your_app) is the
+  [`ExternalContext`](/call/from_outside_your_app) is the
   one context type that retries individual calls, and it retries
   `Unavailable` with no attempt limit — so the call waits for the app
   to come back instead of failing.
@@ -117,7 +117,7 @@ A few rules the harness enforces:
 ##### Failing inside a method, not between calls
 
 A restart _between_ two calls only exercises a boundary the app
-would survive anyway. To make the failure land in the middle of a
+would survive anyway. To make the failure happen in the middle of a
 method — half a workflow done, a task picked up but unfinished —
 replace that method with one that blocks until the test has taken
 the app down:
@@ -188,6 +188,70 @@ revision = await self.rbt.up(
 )
 ```
 
+### Testing signed-in users
+
+Applications with a [`User` type](/users/overview) need their tests to
+act as somebody. `create_external_context_as` mints a real access
+token — through the same code path a real sign-in goes through, so the
+caller's `User` is auto-constructed as a side effect — and returns an
+`ExternalContext` authenticated as that user:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../tests/reboot/documentation/test_ai_chat_counter.py&lines=27-30) -->
+<!-- The below code snippet is automatically added from ../../tests/reboot/documentation/test_ai_chat_counter.py -->
+
+```py
+self.context = await self.rbt.create_external_context_as(
+    name=f"test-{self.id()}",
+    user_id=_OWNER_ID,
+)
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+Call `up()` first: it guarantees an OAuth server to mint through,
+auto-supplying a test provider when your application has no `oauth=`
+of its own.
+
+Every call made with that context arrives authenticated as `user_id`,
+so this is also how you check that
+[authorizers](/users/authorization) really do keep users apart — mint
+a second context as somebody else and assert that it is refused:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../tests/reboot/documentation/test_ai_chat_counter.py&lines=72-91) -->
+<!-- The below code snippet is automatically added from ../../tests/reboot/documentation/test_ai_chat_counter.py -->
+
+```py
+async def test_non_owner_cannot_read_counter(self) -> None:
+    create_response = await User.ref(_OWNER_ID).create_counter(
+        self.context,
+        description="private counter",
+    )
+
+    # A second signed-in user, with a valid token but a different
+    # `user_id`, must not be able to read a counter they do not
+    # own: the `_caller_is_owner` authorizer refuses them. A fresh
+    # `ref` is required per context.
+    other_context = await self.rbt.create_external_context_as(
+        name=f"other-{self.id()}",
+        user_id="other-user",
+    )
+    with self.assertRaises(Aborted):
+        await Counter.ref(create_response.counter_id).get(other_context)
+
+    # The owner still can.
+    owner_counter = Counter.ref(create_response.counter_id)
+    self.assertEqual((await owner_counter.get(self.context)).value, 0)
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+Two lower-level helpers are available when you need them:
+
+| Helper | Use it for |
+| --- | --- |
+| `make_valid_oauth_access_token(user_id=..., claims=...)` | A raw bearer token. Pass `claims=` to exercise a servicer's [`set_claims`](/users/claims). |
+| `make_jwt(**claims)` | An arbitrary JWT signed with the test signing secret, for testing your own [`TokenVerifier`](/users/tokens). |
+
 ### TypeScript
 
 For TypeScript, you can use the `Reboot` class from the `@reboot-dev/reboot` package to start your servicer,
@@ -195,8 +259,8 @@ create a context, and call the methods you want to test.
 With the Node.js built-in test runner, call subtests through the `t` argument (`t.test(...)`) and remember to `await` them.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/chat-room-nodejs/backend/tests/test.ts&lines=2-36) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room-nodejs/backend/tests/test.ts -->
+(CODE:src=../../reboot/examples/chat-room-nodejs/backend/tests/test.ts&lines=2-36) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/chat-room-nodejs/backend/tests/test.ts -->
 
 ```ts
 import { Application, Reboot } from "@reboot-dev/reboot";
@@ -241,8 +305,8 @@ If you prefer to write tests in [BDD](https://en.wikipedia.org/wiki/Behavior-dri
 you can easily set up Reboot yourself in the test preparations, too.
 
 <!-- MARKDOWN-AUTO-DOCS:START
-(CODE:src=../../../reboot/examples/chat-room-nodejs/backend/tests/test_bdd.ts&lines=5-39) -->
-<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room-nodejs/backend/tests/test_bdd.ts -->
+(CODE:src=../../reboot/examples/chat-room-nodejs/backend/tests/test_bdd.ts&lines=5-39) -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/chat-room-nodejs/backend/tests/test_bdd.ts -->
 
 ```ts
   ChatRoom,
@@ -282,7 +346,7 @@ describe("ChatRoom Servicer", async () => {
     });
 ```
 
-<!-- The below code snippet is automatically added from ../../../reboot/examples/chat-room-nodejs/backend/tests/test_bdd.ts -->
+<!-- The below code snippet is automatically added from ../../reboot/examples/chat-room-nodejs/backend/tests/test_bdd.ts -->
 <!-- MARKDOWN-AUTO-DOCS:END -->
 
 #### Vitest
@@ -305,5 +369,5 @@ export default defineConfig({
 ## Calling your endpoint from outside of an app
 
 You can call your servicer methods from outside of a Reboot app using
-an [`ExternalContext`](/learn_more/call/from_outside_your_app) or directly
-with an [`HTTP`](/learn_more/call/via_http) request.
+an [`ExternalContext`](/call/from_outside_your_app) or directly
+with an [`HTTP`](/call/via_http) request.
diff --git a/documentation/docs/tools/cli.md b/documentation/docs/tools/cli.md
deleted file mode 100644
index 26d33e640..000000000
--- a/documentation/docs/tools/cli.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Using the `rbt` CLI
-
-## Bring your own certificate with `rbt dev run`
-By default `rbt dev run` backends use plain HTTP, not HTTPS. This makes for
-easier development, but due to web browser limitations the number of connections
-to the backend over HTTP will be limited - beyond 200 connections it is required
-to use HTTPS. To enable HTTPS you must provide your own TLS certificate when
-running `rbt dev run`.
-
-### Generating a Certificate with [mkcert](https://github.com/FiloSottile/mkcert)
-
-You can use `mkcert` to issue a certificate. Follow these steps:
-
-* Install `mkcert`: Refer to the instructions in the [`mkcert README`](https://github.com/FiloSottile/mkcert/blob/master/README.md) for installation.
-* Install the root certificate: Run the following command: `mkcert -install`.
-* Issue a certificate: `mkcert localhost`.
-
-:::note
-Running `mkcert <domain>` will issue a certificate for the specified domain. For
-local development, it is recommended to include `localhost` in the certificate's
-Subject Alternative Names. If you use a custom domain, ensure it points to
-`127.0.0.1` in your `/etc/hosts` file for `rbt dev run` to work seamlessly.
-:::
-
-### Configuring `rbt dev run` with the Certificate
-
-Once the certificate is issued, configure `rbt dev run` with the following flags:
-
-* `--tls-certificate=<path>` - The path to the certificate file (e.g. `localhost.pem`).
-* `--tls-key=<path>` - The path to the key file (e.g. `localhost-key.pem`).
-* `--tls-root-certificate=<path>` - The path to the root certificate file (e.g. `rootCA.pem`).
-  To locate the root certificate, use: `mkcert -CAROOT`.
-
-### Updating Reboot React Endpoint
-
-:::note
-Make sure to update the [`RebootClientProvider's
-url`](https://github.com/reboot-dev/reboot-hello/blob/main/web/src/index.tsx#L16)
-to use HTTPS when using a custom certificate.
-:::
-
-This setup ensures secure local development with custom certificates and enables
-compatibility with `rbt dev run`.
diff --git a/documentation/docs/users/authorization.mdx b/documentation/docs/users/authorization.mdx
new file mode 100644
index 000000000..50cfd4a45
--- /dev/null
+++ b/documentation/docs/users/authorization.mdx
@@ -0,0 +1,348 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Authorization
+
+[Sign-in](/users/overview) establishes *who* is calling. Authorization
+decides *what they may do*. In Reboot you declare that once per
+servicer, as a rule for each of its methods, and Reboot enforces the
+rule before the method runs — rather than an `if` statement buried in
+every method body.
+
+Every call is checked in two steps:
+
+1. **Token verification** turns the caller's credential into an `Auth`
+   object with a `user_id` (and any other properties you put on it).
+   With [`oauth=`](/users/oauth) configured, Reboot does this for you;
+   see [Bearer tokens](/users/tokens) for doing it yourself.
+2. **Authorizers** decide, per method, whether that caller may
+   proceed.
+
+## Defaults you get for free
+
+Before writing any authorizer, know what you already have:
+
+- **`User` methods** are callable by that user, and by your own
+  application code. Nobody else.
+- **Every other state type** is callable only by your own application
+  code. A call arriving from outside is denied.
+
+For a great many applications that is the entire authorization model:
+users reach their own `User`, `User` methods reach everything else on
+their behalf, and no external caller can address your internal types
+directly.
+
+### Overriding the defaults
+
+Implementing `authorizer()` on a servicer replaces that type's default
+entirely; nothing from it carries over. If your own application code
+should still be able to call a method, allow that explicitly with
+`is_app_internal`. On a `User` servicer, likewise re-state the owner
+rule with `state_id_is_user_id` if you still want it:
+
+```python
+return User.Authorizer(
+    profile=allow_if(any=[state_id_is_user_id, is_app_internal]),
+    # ...
+)
+```
+
+Both callables are described under
+[Built-in callables](#built-in-callables) below.
+
+### Relaxed during development
+
+Under `rbt dev run`, a call from outside to a type that has no
+`authorizer()` is **allowed** rather than denied, so you can build the
+app before deciding who may call what. Each such call logs a warning:
+
+```
+*** TodoList.todos IS MISSING AUTHORIZATION *** Calls to this method are ONLY ALLOWED during development and will be DENIED in production. See https://docs.reboot.dev/users/authorization#relaxed-during-development for more details. Will silence this message for the next 1 minute.
+```
+
+Under `rbt serve` and on Reboot Cloud those calls are denied.
+Implementing `authorizer()` on the servicer silences the warning. The
+`User` default is not relaxed; it applies in development too.
+
+## Writing an authorizer
+
+Implement `authorizer()` on your [servicer](/implement/servicers) and
+give a rule per method:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/backend/src/servicers/counter.py&lines=72-84&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/backend/src/servicers/counter.py -->
+
+```python
+class CounterServicer(Counter.Servicer):
+    """Servicer for the Counter state machine."""
+
+    def authorizer(self) -> Authorizer:
+        return Counter.Authorizer(
+            # `create` is restricted to trusted app code and records
+            # the counter's owner; every other method is restricted to
+            # that owner (or, again, to trusted app code).
+            create=allow_if(all=[is_app_internal]),
+            get=allow_if(any=[_caller_is_owner, is_app_internal]),
+            increment=allow_if(any=[_caller_is_owner, is_app_internal]),
+            description=allow_if(any=[_caller_is_owner, is_app_internal]),
+        )
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+```ts
+import { allow, allowIf } from "@reboot-dev/reboot";
+
+class AccountServicer extends Account.Servicer {
+
+  authorizer() {
+    return new Account.Authorizer({
+      balance: allowIf({ any: [isAdmin, isAccountOwner] }),
+      deposit: allow(),
+      withdraw: allowIf({ all: [isAccountOwner] }),
+      ...
+    });
+  }
+
+  ...
+```
+  </TabItem>
+</Tabs>
+
+You can also return a single rule directly from `authorizer()`, which
+then applies to every method on the type:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+```py
+from reboot.aio.auth.authorizers import allow_if
+
+class AccountServicer(Account.Servicer):
+
+    def authorizer(self):
+        return allow_if(all=[is_admin])
+
+    ...
+```
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+```ts
+import { allowIf } from "@reboot-dev/reboot";
+
+class AccountServicer extends Account.Servicer {
+
+  authorizer() {
+    return allowIf({ all: [isAdmin] });
+  }
+
+  ...
+```
+  </TabItem>
+</Tabs>
+
+## Rules
+
+Rules come from `reboot.aio.auth.authorizers` (Python) or
+`@reboot-dev/reboot` (TypeScript).
+
+### `deny()`
+
+Denies every request, your own application's included. Use it to
+take a method out of service without removing it:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+```python
+from reboot.aio.auth.authorizers import deny
+
+class TodoListServicer(TodoList.Servicer):
+
+    def authorizer(self):
+        return TodoList.Authorizer(
+            # Not ready yet: nobody may call it.
+            share=deny(),
+            # ...
+        )
+```
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+```ts
+import { deny } from "@reboot-dev/reboot";
+
+class TodoListServicer extends TodoList.Servicer {
+  authorizer() {
+    return new TodoList.Authorizer({
+      // Not ready yet: nobody may call it.
+      share: deny(),
+      // ...
+    });
+  }
+}
+```
+  </TabItem>
+</Tabs>
+
+### `allow()`
+
+Allows every request. Use it deliberately — it makes the method
+callable by anyone who can reach your backend, signed in or not:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+```python
+from reboot.aio.auth.authorizers import allow
+
+class TodoListServicer(TodoList.Servicer):
+
+    def authorizer(self):
+        return TodoList.Authorizer(
+            # Anyone may read a list.
+            todos=allow(),
+            # ...
+        )
+```
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+```ts
+import { allow } from "@reboot-dev/reboot";
+
+class TodoListServicer extends TodoList.Servicer {
+  authorizer() {
+    return new TodoList.Authorizer({
+      // Anyone may read a list.
+      todos: allow(),
+      // ...
+    });
+  }
+}
+```
+  </TabItem>
+</Tabs>
+
+### `allow_if()`
+
+Takes a set of *authorizer callables* — the functions that make the
+actual decision. Each returns an `Authorizer.Decision`: `Ok`,
+`PermissionDenied`, or `Unauthenticated`.
+
+Pass them via `all` to require that *every* callable decides `Ok`, or
+via `any` to allow the call when *at least one* does:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+```python
+from reboot.aio.auth.authorizers import allow_if, is_app_internal
+
+class TodoListServicer(TodoList.Servicer):
+
+    def authorizer(self):
+        return TodoList.Authorizer(
+            # Only your own application code may create a list.
+            create=allow_if(all=[is_app_internal]),
+            # The list's owner may add to it; so may your own code.
+            add=allow_if(any=[_caller_is_owner, is_app_internal]),
+        )
+```
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+```ts
+import { allowIf, isAppInternal } from "@reboot-dev/reboot";
+
+class TodoListServicer extends TodoList.Servicer {
+  authorizer() {
+    return new TodoList.Authorizer({
+      // Only your own application code may create a list.
+      create: allowIf({ all: [isAppInternal] }),
+      // The list's owner may add to it; so may your own code.
+      add: allowIf({ any: [callerIsOwner, isAppInternal] }),
+    });
+  }
+}
+```
+  </TabItem>
+</Tabs>
+
+`_caller_is_owner` (`callerIsOwner`) is written in the next section.
+
+## Authorizer callables
+
+A callable receives the `context`, the instance's `state`, and the
+`request`, and returns a decision. Here is one that allows the owner
+of a `Counter` and nobody else:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/backend/src/servicers/counter.py&lines=20-33&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../reboot/examples/ai-chat-counter/backend/src/servicers/counter.py -->
+
+```python
+def _caller_is_owner(
+    *,
+    context: ReaderContext,
+    state: Optional[Counter.State],
+    **kwargs,
+):
+    """Allow when the caller's `user_id` matches the Counter's recorded
+    `owner_id`. A not-yet-constructed Counter (`state is None`) falls
+    through to deny."""
+    if context.auth is None or not context.auth.user_id:
+        return Unauthenticated()
+    if state is not None and context.auth.user_id == state.owner_id:
+        return Ok()
+    return PermissionDenied()
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+Note the pattern: it reads the caller's identity off `context.auth`,
+compares it against durable state, and returns a decision. It does not
+raise, and it does not mutate anything.
+
+### Built-in callables
+
+Reboot ships the ones almost every application needs:
+
+| Callable | Decides `Ok` when |
+| --- | --- |
+| `is_app_internal` | The call originates inside your own application rather than from a client. |
+| `state_id_is_user_id` | The caller's `user_id` equals the instance's state ID — the rule behind the `User` default. |
+| `has_verified_token` | The caller presented a token that verified. Says nothing about *which* user it is. |
+
+:::note
+
+Verifying a token and running authorizers *must not have effects*, so
+they always receive a `ReaderContext` regardless of the
+[kind of method](/define/methods) being authorized.
+
+:::
+
+## A pattern that works
+
+The combination in the `Counter` example above generalizes well:
+
+```py
+create=allow_if(all=[is_app_internal]),
+get=allow_if(any=[_caller_is_owner, is_app_internal]),
+```
+
+- Construction is **application-internal only**, so instances are only
+  ever created through a `User` method that records who owns them.
+- Every other method allows the recorded owner, or trusted application
+  code.
+
+That gives you per-instance ownership without a permissions table, and
+it holds no matter which surface the call arrives from — web, native,
+or an AI chat client.
+
+## Next
+
+- [Bearer tokens and token verification](/users/tokens) — bringing
+  your own credentials.
+- [Users and sign-in](/users/overview) — where `context.auth.user_id`
+  comes from.
+- [Errors](/errors) — what a denied call looks like to the caller.
diff --git a/documentation/docs/users/claims.mdx b/documentation/docs/users/claims.mdx
new file mode 100644
index 000000000..230b528b3
--- /dev/null
+++ b/documentation/docs/users/claims.mdx
@@ -0,0 +1,158 @@
+# Identity claims
+
+Sign-in gives you a stable user ID. Often you want a little more: the
+person's verified email address so you can mail them, their name so
+you can greet them, their picture so you can show an avatar.
+
+Those are **identity claims** — facts about the user that your
+[OAuth provider](/users/providers) has verified. Ask for them on the
+provider, and Reboot delivers them to your `User` on every sign-in.
+
+## Asking for claims
+
+Pass `claims=` to the OAuth provider:
+
+```python
+Google(
+    client_id=...,
+    client_secret=...,
+    claims=["email", "email_verified", "name"],
+)
+```
+
+Which claims a provider can deliver is fixed and checked at
+construction time. See [OAuth providers](/users/providers) for the
+claims each one can deliver.
+
+Pass a mapping instead of a list to present a claim under a different
+name:
+
+```python
+claims={"email": "verified_email"}
+```
+
+Leaving `claims=` off entirely — the default — turns claim delivery
+off. Reboot then knows only the user's ID.
+
+## Receiving claims
+
+Claims arrive through a `set_claims` method that the framework injects
+on your `User` type. Override it in your servicer:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/backend/src/servicers/todos.py&lines=57-66&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/backend/src/servicers/todos.py -->
+
+```python
+async def set_claims(
+    self,
+    context: TransactionContext,
+    request: User.SetClaimsRequest,
+) -> None:
+    """Runs on every sign-in with the identity provider's verified
+    claims, which are the complete, current set: derive all
+    claim-backed state from them rather than merging."""
+    self.state.name = request.claims.get("name", "")
+    self.state.email = request.claims.get("email", "")
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+`request.claims` is a `dict[str, Any]`, keyed by the presented claim
+names, carrying the values verbatim as the provider sent them.
+
+Three rules govern it:
+
+1. **It is a full replace.** Every delivery carries the *complete,
+   current* set of verified claims. Derive all your claim-backed state
+   from it, rather than merging into what you had.
+2. **It must be idempotent.** `set_claims` runs on *every* sign-in,
+   not just the first, so re-delivering identical claims has to be
+   harmless.
+3. **A claim can be missing.** Providers omit claims they do not have
+   for a user. Use `.get()` with a default rather than indexing.
+
+:::note
+If claims are delivered and your servicer has not overridden
+`set_claims`, Reboot raises. Either override the method, or stop
+requesting claims.
+:::
+
+## When claims are delivered
+
+Claims are delivered on a sign-in, not on a token refresh, and the
+previously delivered claims stand until the next sign-in. So a user
+who changes their email address at the provider propagates that change
+to your application when they next sign in. If that is too late for
+your application and you use Ory, read on.
+
+## Keeping claims fresh with Ory
+
+[`Ory`](/users/providers#ory) can push identity changes to your
+application as they happen. Pass a `webhook_secret` (it requires
+`claims=`) and Reboot exposes `POST /__/oauth/ory/webhook`:
+
+```python
+Ory(
+    domain=os.environ.get("ORY_DOMAIN"),
+    client_id=os.environ.get("ORY_CLIENT_ID"),
+    client_secret=os.environ.get("ORY_CLIENT_SECRET"),
+    claims=["email", "email_verified"],
+    webhook_secret=os.environ.get("ORY_WEBHOOK_SECRET"),
+)
+```
+
+Then configure an Ory Action to call it after the settings flow. In
+the Ory project config, under `selfservice.flows.settings.after`:
+
+```yaml
+hooks:
+  - hook: web_hook
+    config:
+      url: https://<your-backend-url>/__/oauth/ory/webhook
+      method: POST
+      # Jsonnet: function(ctx) { identity: ctx.identity }
+      body: base64://ZnVuY3Rpb24oY3R4KSB7IGlkZW50aXR5OiBjdHguaWRlbnRpdHkgfQ==
+      auth:
+        type: api_key
+        config:
+          name: x-ory-webhook-key
+          value: <webhook_secret>
+          in: header
+```
+
+The webhook expects a JSON body shaped like
+`{"identity": {"id": ..., "traits": {...}, ...}}`, which the Jsonnet
+above produces, and delivers the identity's claims to the same
+`set_claims` method a sign-in does.
+
+Two limits:
+
+- **It never creates a `User`.** Claims are delivered only to a `User`
+  that already exists; an identity that has never signed in is left
+  alone.
+- **Admin-API edits do not fire it.** Identity changes made through
+  Ory's admin API do not run flow-scoped actions, so those still
+  propagate at the user's next sign-in.
+
+Treat `webhook_secret` like `client_secret`: deliver it as a
+[secret](/secrets). Leave it off to keep the route unexposed.
+
+## Claims in local development
+
+[`Development`](/users/providers#development) fabricates `email`,
+`email_verified`, and `name` for its fake identities, so you can
+exercise `set_claims` without registering with a real provider:
+
+```python
+OAuthProviderByEnvironment(
+    dev=Development(claims=["email", "name"]),
+    prod=Google(..., claims=["email", "name"]),
+)
+```
+
+## Claims are not authorization
+
+A claim tells you something the provider has verified about the user.
+It is not a permission. Decide what a caller may do in an
+[authorizer](/users/authorization), keyed on the user's ID — not on an
+email domain or a name you happened to receive.
diff --git a/documentation/docs/users/external_apis.mdx b/documentation/docs/users/external_apis.mdx
new file mode 100644
index 000000000..a954b11a7
--- /dev/null
+++ b/documentation/docs/users/external_apis.mdx
@@ -0,0 +1,195 @@
+# Call external APIs as the user
+
+Signing a user in tells you *who* they are. Sometimes you also want to
+act *as them* somewhere else: read their Google Calendar, open a pull
+request on their GitHub, post to their Slack.
+
+That always has two halves:
+
+1. **Capture** the external service's OAuth tokens once, stored
+   encrypted in an
+   [`OAuthTokenManager`](/library_services/oauth_token_manager) — one
+   manager per external service.
+2. **Use** them: fetch the tokens back and make the outbound call from
+   a [workflow](/implement/workflows).
+
+How you capture depends on *whose* API you want to call.
+
+## Your identity provider's own API
+
+If the API belongs to the provider your users already sign in with,
+Reboot captures its tokens for you. Ask for the extra OAuth
+`scopes=[...]` your calls need — on top of the identity scope the
+provider always requests — and pass `store_tokens=True`:
+
+```py
+def _google() -> Google:
+    return Google(
+        client_id=os.environ.get("GOOGLE_OAUTH_CLIENT_ID"),
+        client_secret=os.environ.get("GOOGLE_OAUTH_CLIENT_SECRET"),
+        # Request the least you need.
+        scopes=["https://www.googleapis.com/auth/calendar.events"],
+        store_tokens=True,
+    )
+
+oauth=OAuth(
+    provider=OAuthProviderByEnvironment(
+        # `Development()` issues no tokens, so to exercise the
+        # provider's API locally use the real provider in `dev=` too.
+        dev=_google(),
+        prod=_google(),
+    ),
+    allowed_origins=["https://app.example.com"],
+)
+```
+
+On each sign-in, Reboot captures the provider's access and refresh
+tokens and stores them, encrypted, in the `OAuthTokenManager` for that
+provider. Your code reads them back with
+[`OAuthTokenManager.fetch`](/library_services/oauth_token_manager#fetch),
+as shown under [Using the tokens](#using-the-tokens) below.
+
+This needs the `OAuthTokenManager` library on your `Application`; see
+[Imports and servicers](/library_services/oauth_token_manager#imports-and-servicers)
+for the lines to add.
+
+:::important
+
+**Reboot stores only the provider's *own* tokens.** This matters most
+with a broker like `Auth0` or `Ory`: when a user signs in "with
+Google" through Auth0, what gets stored is an **Auth0** token. It
+authorizes Auth0's APIs, not Google's.
+
+To call the upstream service in that case, either retrieve the
+federated provider's token from the broker (Auth0 keeps it on the
+user's profile, retrievable via its Management API with the
+`read:user_idp_tokens` scope), or capture the upstream service's
+tokens yourself, as described next.
+
+:::
+
+## Any other OAuth service
+
+When the service is *not* your identity provider — your users sign in
+with Google but you want their Slack — there is no shortcut. A Google
+grant only authorizes Google's APIs.
+
+Run the other service's OAuth flow yourself with your own HTTP
+routes, then store what it issues in that service's
+`OAuthTokenManager`, so that **all** of your application's OAuth
+tokens live in the same kind of store:
+
+1. Register an **authorize** route that redirects the browser to the
+   service's authorize URL — your client ID, the scopes you need, your
+   callback as the redirect URI, and a signed `state` carrying the
+   signed-in user's ID.
+2. Register a **callback** route that verifies the `state`, exchanges
+   the `code` at the service's token endpoint, and calls
+   [`OAuthTokenManager.store`](/library_services/oauth_token_manager#store)
+   under a service ID of your choosing (e.g. `"slack.com"`).
+
+`OAuthTokenManager`'s methods are application-internal, so the
+callback route must opt into an application-internal context:
+
+```py
+# In `main()`, after constructing `application`:
+application.http.get("/__/oauth/slack/authorize")(slack_authorize)
+application.http.get("/__/oauth/slack/callback", app_internal=True)(
+    slack_callback
+)
+```
+
+:::caution
+
+`app_internal=True` makes the route's calls count as your own
+application's, so the [default authorizer](/users/authorization#defaults-you-get-for-free),
+and any `is_app_internal` rule you wrote, lets them through. Only set
+it on a route you are certain serves trusted traffic — here, a
+callback that runs only after you have verified the OAuth `state` you
+issued. Never set it on a route that acts on unvalidated request
+input.
+
+:::
+
+## Using the tokens
+
+Reading tokens back and calling the service is the same however they
+were captured. The outbound HTTP call belongs in a
+[workflow](/implement/workflows), wrapped in
+[`at_least_once` or `at_most_once`](/implement/workflows#at-least-or-at-most-once)
+like any other [side effect](/side_effects):
+
+```py
+from rbt.std.oauth.v1.oauth_rbt import OAuthTokenManager
+from reboot.aio.workflows import at_least_once
+from reboot.std.oauth.v1.oauth import GOOGLE
+
+@classmethod
+async def create_event(
+    cls,
+    context: WorkflowContext,
+    request: User.CreateEventRequest,
+) -> User.CreateEventResponse:
+    stored = await OAuthTokenManager.ref(GOOGLE).fetch(
+        context, user_id=context.state_id,
+    )
+    if not stored.found:
+        # Not connected yet: surface a "connect" path, don't crash.
+        return User.CreateEventResponse(connected=False)
+
+    async def do_create():
+        return await calendar_api.create_event(
+            access_token=stored.tokens.access_token,
+            summary=request.summary,
+        )
+
+    result = await at_least_once("Create event", context, do_create)
+    return User.CreateEventResponse(connected=True)
+```
+
+## Services that use an API key instead
+
+Some services have no per-user OAuth; the user gives your application
+an API key or personal access token instead.
+
+:::note
+
+This section is about a key **the user** provides so your application
+can act *as that user* — a per-user secret, stored per user. A key
+**you, the developer,** hold for the whole application (your Stripe
+secret key, your OpenAI key) is not per-user state and does not belong
+in application state at all: deliver it as an application
+[secret](/secrets) via environment variables.
+
+:::
+
+`OAuthTokenManager` is purpose-built for OAuth tokens; do not shoehorn
+an API key into it. The key is still a secret at rest, so encrypt it
+with [`Ciphertext`](/library_services/ciphertext) and keep the
+returned `Ciphertext` state ID — itself a harmless string — in your
+state as the reference to the encrypted value:
+
+```py
+ciphertext, _ = await Ciphertext.encrypt(
+    context,
+    plaintext=request.api_key.encode(),
+    associated_data=make_associated_data(
+        user_id=user_id, purpose="acme-api-key",
+    ),
+    scope=f"user:{user_id}",  # The crypto-shred unit.
+    key_manager_id=APP_SHARED_KEY_MANAGER_ID,
+)
+# The reference to the encrypted key; never the key itself.
+self.state.acme_api_key_id = ciphertext.state_id
+```
+
+To use it, `decrypt` (with the same `associated_data`) and make the
+call from a workflow, exactly as above.
+
+## Erasing a user's credentials
+
+Both stores support per-user erasure by crypto-shredding: see
+[erasing a user's tokens](/library_services/oauth_token_manager#erasing-a-users-tokens)
+for `OAuthTokenManager`, and
+[crypto-shred](/library_services/ciphertext#crypto-shred-shred) for
+`Ciphertext`-encrypted API keys.
diff --git a/documentation/docs/users/oauth.mdx b/documentation/docs/users/oauth.mdx
new file mode 100644
index 000000000..33a1b6d6f
--- /dev/null
+++ b/documentation/docs/users/oauth.mdx
@@ -0,0 +1,179 @@
+# Configure OAuth
+
+Reboot runs an OAuth 2.1 authorization server as part of your
+application. You do not stand one up, register your app with it, or
+write a callback handler — you hand `Application` an `OAuth` and it
+mounts the whole thing.
+
+```python
+from reboot.aio.applications import Application
+from reboot.aio.auth.oauth import OAuth
+from reboot.aio.auth.oauth_providers import (
+    Development,
+    Google,
+    OAuthProviderByEnvironment,
+)
+
+await Application(
+    servicers=[UserServicer, ...],
+    oauth=OAuth(
+        provider=OAuthProviderByEnvironment(
+            dev=Development(),
+            prod=Google(
+                client_id=os.environ.get("GOOGLE_OAUTH_CLIENT_ID"),
+                client_secret=os.environ.get("GOOGLE_OAUTH_CLIENT_SECRET"),
+            ),
+        ),
+        allowed_origins=["https://app.example.com"],
+    ),
+).run()
+```
+
+That gives you sign-in for browsers, native apps, and AI chat clients,
+sessions that stay signed in, sign-out, and
+[`User` auto-construction](/users/overview) — from those few lines.
+
+:::note Python today
+`Application(oauth=...)` is currently Python-only. TypeScript backends
+authenticate callers with
+[`token_verifier=`](/users/tokens) instead.
+:::
+
+## `OAuth` options
+
+| Parameter | Description |
+| --- | --- |
+| `provider` | Required. An `OAuthProviderSelector` that picks which [OAuth provider](/users/providers) identifies users. |
+| `allowed_origins` | The browser origins allowed to make credentialed requests to your backend. Required in production. |
+| `skip_consent_for_redirect_uris` | Redirect URIs whose clients you already trust, so their users sign in without a consent screen. |
+
+### `provider`
+
+`provider` takes a *selector*, not a provider, so the choice can depend
+on where the application is running:
+
+```python
+provider=OAuthProviderByEnvironment(
+    dev=Development(),
+    prod=Google(...),
+)
+```
+
+`OAuthProviderByEnvironment` returns the `dev` arm under `rbt dev run`
+and the `prod` arm everywhere else — `rbt serve`, Reboot Cloud, and
+any environment Reboot cannot classify.
+
+Both arms must be passed explicitly, so the choice for each
+environment is deliberate, but either may be `None`. A `None` arm that
+is actually selected fails at startup. A provider checks its
+credentials only when it is selected, too, which is why the examples
+read them with `os.environ.get(...)`: the `prod` arm can be written
+down before its environment variables exist.
+
+```python
+provider=OAuthProviderByEnvironment(
+    dev=Development(),
+    # TODO: pick a real provider before deploying; `None` makes a
+    # production start fail loudly until you do.
+    prod=None,
+)
+```
+
+### `allowed_origins`
+
+`allowed_origins` is the exact-match list of HTTP origins
+(`scheme://host[:port]`) that browsers may make signed-in requests
+from.
+
+Your backend's own origin is always trusted, so a same-origin browser
+client works no matter what. `allowed_origins` only ever widens trust
+to additional, cross-origin front ends:
+
+```python
+allowed_origins=["https://app.example.com", "https://staging.example.com"]
+```
+
+- **In development** (`rbt dev run`), `http://localhost` and
+  `http://127.0.0.1` on any port are allowed automatically, so a Vite
+  or webpack dev server works without configuration.
+- **In production**, leaving `allowed_origins` unset is a hard error
+  at construction time. Pass your web app's real origin, or pass an
+  explicit empty list (`allowed_origins=[]`) to opt into
+  same-origin-only browser auth.
+
+Entries must be bare origins (`scheme://host[:port]`): a trailing
+slash, path, query, or fragment is rejected. Matching is exact;
+wildcards are not supported.
+
+### `skip_consent_for_redirect_uris`
+
+A client that cannot use the browser sign-in flow — an AI chat client,
+a native app — registers itself with Reboot's OAuth server.
+
+Registration proves nothing about who is registering, so by default
+Reboot shows the user a **consent screen** naming the client and the
+redirect URI its tokens will be sent to.
+
+List a redirect URI here to say you already trust whoever receives a
+code at it — typically your own first-party apps:
+
+```python
+skip_consent_for_redirect_uris=[
+    "myapp://redirect",                    # Custom scheme.
+    "https://myapp.example.com/redirect",  # App Link / Universal Link.
+]
+```
+
+Entries are compared for exact equality, and wildcards are refused.
+Under `rbt dev run`, Expo's `exp://<host>/--/...` development URIs skip
+consent automatically.
+
+:::tip Prefer a verified link
+A custom scheme like `myapp://` can be claimed by another app on the
+same device. An `https://` App Link or Universal Link, which the
+operating system verifies against your domain, cannot.
+:::
+
+## Going to production
+
+Four things to get right before you deploy:
+
+**1. Register Reboot's callback URL.** In your identity provider's own
+console, add
+
+```
+https://<your-backend-url>/__/oauth/callback
+```
+
+as an authorized redirect URI, using the backend's public URL, not
+the web app's. This is the single most common cause of a sign-in that
+works locally and fails in production.
+
+**2. Deliver client credentials as secrets.** Client IDs and secrets
+belong in environment variables, never in source. See
+[Secrets](/secrets), and `rbt cloud secret set` if you deploy on
+[Reboot Cloud](/deploy_on_reboot_cloud).
+
+**3. Set `allowed_origins`.** See
+[above](#allowed_origins) — production refuses to start without it.
+
+**4. Set `REBOOT_CRYPTO_ROOT_KEYS`.** Reboot derives the key it signs
+session tokens with from your application's cryptographic root keys,
+and every server process must agree on them. `rbt dev run` and Reboot
+Cloud set this for you; if you run
+[`rbt serve`](/deploy_on_your_own) yourself, you must provide it.
+
+:::caution Rotating root keys signs everyone out
+Rotating the root keys invalidates every outstanding token and sends
+every client back through the sign-in flow.
+:::
+
+## Next
+
+- [OAuth providers](/users/providers) — what to put in `dev=` and
+  `prod=`.
+- [Identity claims](/users/claims) — get the user's email and name.
+- [Users and sign-in](/users/overview) — what happens to your `User`
+  when somebody signs in.
+- [Bearer tokens](/users/tokens) — accepting tokens minted somewhere
+  else, alongside or instead of Reboot's own.
diff --git a/documentation/docs/users/overview.mdx b/documentation/docs/users/overview.mdx
new file mode 100644
index 000000000..5411c952c
--- /dev/null
+++ b/documentation/docs/users/overview.mdx
@@ -0,0 +1,443 @@
+# Users and sign-in
+
+Nearly every application starts from the same question: *who is
+this?* Getting the answer right means an OAuth flow, a session, token
+refresh, per-user authorization, and a "find or create the user"
+helper nobody remembers to call — a pile of code that is easy to write
+badly and no fun to review.
+
+So Reboot solves it once, at the framework level. Declare a type named
+`User`, tell your `Application` how people sign in, and Reboot does
+the rest: it serves the sign-in flow, establishes the caller's
+identity, and **auto-constructs a `User` instance for them**. That
+instance is the entry point for everything else your application knows
+about that person.
+
+There is no sign-up form to write, no session table to keep, and
+nothing for you — or your coding agent — to get subtly wrong.
+
+## The `User` type
+
+Naming a type `User` in your API definition is what turns this on.
+Here it is in a todo-list app, where a `User` is the person: their
+profile, and the lists they own. The lists themselves are their own
+type.
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/todos.py&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/todos.py -->
+
+```python
+# api/todos/v1/todos.py
+from reboot.api import (
+    API,
+    Field,
+    Methods,
+    Model,
+    Reader,
+    Tool,
+    Transaction,
+    Type,
+    Writer,
+)
+
+
+class UserState(Model):
+    # The person's profile, kept current from the identity provider's
+    # verified claims on every sign-in.
+    name: str = Field(tag=1, default="")
+    email: str = Field(tag=2, default="")
+    # The todo lists this person owns: each list's state ID, and its
+    # title so the lists can be shown without a call per list.
+    todo_lists: dict[str, str] = Field(tag=3, default_factory=dict)
+
+
+class ProfileResponse(Model):
+    name: str = Field(tag=1)
+    email: str = Field(tag=2)
+
+
+class CreateTodoListRequest(Model):
+    title: str = Field(tag=1)
+
+
+class CreateTodoListResponse(Model):
+    todo_list_id: str = Field(tag=1)
+
+
+class TodoListSummary(Model):
+    todo_list_id: str = Field(tag=1)
+    title: str = Field(tag=2)
+
+
+class ListTodoListsResponse(Model):
+    todo_lists: list[TodoListSummary] = Field(tag=1, default_factory=list)
+
+
+class TodoListState(Model):
+    title: str = Field(tag=1, default="")
+    # The `user_id` of the owner, so that only they may read or change
+    # the list.
+    owner_id: str = Field(tag=2, default="")
+    todos: list[str] = Field(tag=3, default_factory=list)
+
+
+class InitializeTodoListRequest(Model):
+    title: str = Field(tag=1)
+    owner_id: str = Field(tag=2)
+
+
+class AddTodoRequest(Model):
+    todo: str = Field(tag=1)
+
+
+class TodosResponse(Model):
+    title: str = Field(tag=1)
+    todos: list[str] = Field(tag=2, default_factory=list)
+
+
+api = API(
+    User=Type(
+        state=UserState,
+        methods=Methods(
+            profile=Reader(
+                request=None,
+                response=ProfileResponse,
+                description="The signed-in user's name and email.",
+                mcp=Tool(),
+            ),
+            create_todo_list=Transaction(
+                request=CreateTodoListRequest,
+                response=CreateTodoListResponse,
+                description="Create a todo list for the signed-in "
+                "user. Returns its `todo_list_id`, which is not "
+                "human-readable but must be passed to tools that "
+                "take one.",
+                mcp=Tool(),
+            ),
+            list_todo_lists=Reader(
+                request=None,
+                response=ListTodoListsResponse,
+                description="List the signed-in user's todo lists: "
+                "`todo_list_id` and title for each.",
+                mcp=Tool(),
+            ),
+        ),
+    ),
+    TodoList=Type(
+        state=TodoListState,
+        methods=Methods(
+            create=Writer(
+                request=InitializeTodoListRequest,
+                response=None,
+                factory=True,
+                description="Create the list with a title and an "
+                "owner.",
+                mcp=None,
+            ),
+            add=Writer(
+                request=AddTodoRequest,
+                response=None,
+                description="Add a todo to the list.",
+                mcp=Tool(),
+            ),
+            todos=Reader(
+                request=None,
+                response=TodosResponse,
+                description="The list's title and its todos.",
+                mcp=Tool(),
+            ),
+        ),
+    ),
+)
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+Three things follow from that name:
+
+1. **Auto-construction.** A `User` instance is created the first time
+   a person signs in, and found again on every sign-in after that.
+   You never call `User.create(...)` yourself.
+2. **The state ID *is* the identity.** The instance's state ID is the
+   stable user ID your [OAuth provider](/users/providers) issues.
+   Inside a `User` servicer method,
+   `context.state_id` is therefore the signed-in person.
+3. **Per-user authorization by default.** A `User`'s methods are
+   callable by that user, and by your own application code, and by
+   nobody else. No `authorizer()` needed. See
+   [Authorization](/users/authorization#defaults-you-get-for-free).
+
+:::info Every field needs a default
+`User` instances are constructed with no arguments, so every field on
+your `User` state must have a default value, or be optional.
+`UserState` may be completely empty, if you only need `User` for
+its methods and its identity.
+:::
+
+## Turning sign-in on
+
+Auto-construction needs to know who is signing in, so an application
+with a `User` type must pass an [`OAuth`](/users/oauth) configuration.
+Starting one without it is an error, not a silent fallback:
+
+```python
+import os
+from reboot.aio.applications import Application
+from reboot.aio.auth.oauth import OAuth
+from reboot.aio.auth.oauth_providers import (
+    Development,
+    Google,
+    OAuthProviderByEnvironment,
+)
+
+async def main() -> None:
+    await Application(
+        servicers=[UserServicer, TodoListServicer],
+        oauth=OAuth(
+            provider=OAuthProviderByEnvironment(
+                dev=Development(),
+                prod=Google(
+                    client_id=os.environ.get("GOOGLE_OAUTH_CLIENT_ID"),
+                    client_secret=os.environ.get(
+                        "GOOGLE_OAUTH_CLIENT_SECRET"
+                    ),
+                ),
+            ),
+            allowed_origins=["https://app.example.com"],
+        ),
+    ).run()
+```
+
+Under `rbt dev run` that uses `Development()`, which serves a fake
+account picker — so you can sign in, and sign in *as somebody else*,
+without registering anything with anyone. Everywhere else it uses the
+`prod` arm, and that is when the environment variables have to be set:
+a provider checks its credentials when it is selected, so the `prod`
+arm can be written down before the credentials exist. See
+[Configure OAuth](/users/oauth) for the full set of options and
+[OAuth providers](/users/providers) for what to put in `prod=`.
+
+## What happens when somebody signs in
+
+The client sends the person to Reboot's sign-in endpoint — a web app
+does this through [`useSignIn()`](#on-the-client), an AI chat client
+as part of connecting. Reboot hands them to your identity provider,
+receives them back, learns their stable ID and any
+[identity claims](/users/claims) you asked for, and **constructs their
+`User` if it does not exist yet**. From then on, every call the client
+makes is authenticated as that person. Signing in for the thousandth
+time constructs nothing: the `User` is simply found again.
+
+## Doing something on first sign-in
+
+Auto-construction calls the `User` type's `create` method. Its default
+implementation does nothing; override it to run whatever a brand-new
+person needs. The todo-list app gives them a first list:
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/backend/src/servicers/todos.py&lines=43-55&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/backend/src/servicers/todos.py -->
+
+```python
+async def create(
+    self,
+    context: TransactionContext,
+) -> None:
+    """Runs once, when a person signs in for the first time: give
+    them a list to start with."""
+    todo_list, _ = await TodoList.create(
+        context,
+        title="Getting started",
+        owner_id=context.state_id,
+    )
+    await todo_list.add(context, todo="Add your first todo")
+    self.state.todo_lists[todo_list.state_id] = "Getting started"
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+`create` is a `transaction`, so anything it touches is committed
+atomically with the construction of the `User` itself: either the person exists
+and has their first list, or neither happened.
+
+:::tip Make it cheap and idempotent
+`create` runs inside the sign-in flow, so keep it fast. Slow work
+(sending mail, calling a third-party API) belongs in a
+[task](/tasks) or [workflow](/implement/workflows) that `create`
+spawns.
+:::
+
+## Using the signed-in user
+
+Inside a `User` servicer method, the signed-in person is
+`context.state_id`. That is what makes `User` the natural place to
+create the things a person owns: it can record who the owner is
+without being told who is calling.
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/backend/src/servicers/todos.py&lines=74-87&syntax=python) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/backend/src/servicers/todos.py -->
+
+```python
+async def create_todo_list(
+    self,
+    context: TransactionContext,
+    request: CreateTodoListRequest,
+) -> CreateTodoListResponse:
+    """Create a list owned by the signed-in person and remember it
+    on their `User`."""
+    todo_list, _ = await TodoList.create(
+        context,
+        title=request.title,
+        owner_id=context.state_id,
+    )
+    self.state.todo_lists[todo_list.state_id] = request.title
+    return CreateTodoListResponse(todo_list_id=todo_list.state_id)
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+Elsewhere — in servicers for your *other* types — the caller's
+identity is on the context's `auth`:
+
+```python
+if context.auth is None or not context.auth.user_id:
+    # Nobody is signed in.
+    ...
+```
+
+That is also what [authorizers](/users/authorization) act on, which is
+usually a better place to put the check than in the method body. The
+todo-list app's `TodoList` servicer uses one to let only the recorded
+owner read or change a list.
+
+On the client, the `user` handle that [`useUser()`](#on-the-client)
+returns carries the same ID as `user.state_id`.
+
+So, wherever you are, the signed-in person's ID is at hand:
+
+| Where | The signed-in user's ID |
+| --- | --- |
+| A `User` servicer method | `context.state_id` |
+| Any other servicer method, or an authorizer | `context.auth.user_id` (`context.auth` is `None` when nobody is signed in) |
+| A React component | `user.state_id`, from `useUser()` |
+
+## `User` as the entry point
+
+Because `User` is the one type whose instance the framework can always
+find, it makes a natural front door for the rest of your application.
+The common pattern, which the todo-list app follows, is:
+
+- `User` methods **create** other state types and remember their IDs
+  (`create_todo_list` returns a `todo_list_id`, and records it on the
+  `User`).
+- `User` methods **list** what this person owns (`list_todo_lists`),
+  so a fresh client — a browser after a reload, or an AI chat client
+  in a brand-new conversation — can find its way back to their state.
+- Everything user-specific is reached from there: their lists, their
+  documents, their settings.
+
+This pattern pays off on every surface. A web app renders the list. A
+chat client calls the same method as a tool and remembers the IDs for
+the rest of the conversation. Neither of them has to be told who the
+user is.
+
+## On the client
+
+On every surface, the client side of all of this is two hooks:
+
+- **`useSignIn()`**, from `@reboot-dev/reboot-react`, starts the
+  sign-in flow: a redirect in a [browser](/surfaces/web#signing-in),
+  a system-browser round trip in a
+  [React Native app](/surfaces/react_native). An
+  [AI chat client](/surfaces/ai_chat) signs the person in when they
+  connect your app, before any `UI` loads, so there is nothing to
+  call.
+- **`useUser()`**, generated from your `User` type, resolves the
+  caller's own `User` when called with no ID: the instance
+  auto-constructed at sign-in. `user` is `undefined` while nobody is
+  signed in, and `isLoading` is `true` while the session is still
+  being resolved.
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/documentation/todos_main.tsx&lines=7-38&syntax=tsx) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/documentation/todos_main.tsx -->
+
+```tsx
+// The signed-in person, or a button to become one. `useUser()` takes
+// no ID: it resolves the caller's own `User`, the instance Reboot
+// auto-constructed when they signed in.
+const Root = () => {
+  const { user, isLoading } = useUser();
+  const signIn = useSignIn();
+
+  if (isLoading) return <p>Checking session…</p>;
+  if (user === undefined) {
+    return <button onClick={() => signIn()}>Sign in</button>;
+  }
+  return <TodoLists user={user} />;
+};
+
+// Everything the app knows about this person hangs off `user`: its
+// readers are reactive hooks, its mutators are plain calls.
+const TodoLists = ({ user }: { user: UseUserApi }) => {
+  const { response } = user.useListTodoLists();
+
+  return (
+    <ul>
+      {(response?.todoLists ?? []).map((todoList) => (
+        <li key={todoList.todoListId}>{todoList.title}</li>
+      ))}
+      <li>
+        <button onClick={() => void user.createTodoList({ title: "New list" })}>
+          New list
+        </button>
+      </li>
+    </ul>
+  );
+};
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+`user` exposes your `User` methods: readers as nested hooks that
+re-render when state changes, mutators as plain calls. There is
+nothing else to set up. (`useSignOut()` exists for the sign-out
+button.)
+
+| Surface | How the flow runs |
+| --- | --- |
+| [Web](/surfaces/web) | `useSignIn()` sends the browser through your identity provider and back. |
+| [React Native](/surfaces/react_native) | `useSignIn()` opens a system browser for your identity provider; the app passes `nativeAuth({...})` to its provider once, and everything else is the same. |
+| [AI chat (MCP)](/surfaces/ai_chat) | The chat client runs the flow itself when the person connects your app. |
+
+Because identity is established by the backend, a person who signs in
+on the web is the *same* `User`, with the same state, in your mobile
+app and in their chat client.
+
+## Choose your identity provider deliberately
+
+:::important
+
+The provider you launch with **fixes your user-ID namespace.** Google,
+GitHub, Auth0 and Ory each issue IDs in their own space, with no
+mapping between them, and those IDs are your `User` state IDs.
+Switching providers once you have real users strands every user-keyed
+piece of state you have.
+
+Pick before you have production users. If you expect to need several
+sign-in methods, or user management beyond a bare ID, start with a
+broker like [Auth0 or Ory](/users/providers) — they let you add and
+change upstream login methods without changing the IDs your
+application sees.
+
+:::
+
+## Where to go next
+
+- [Configure OAuth](/users/oauth) — the `OAuth` options and what
+  production needs.
+- [OAuth providers](/users/providers) — `Development`, `Google`,
+  `GitHub`, `Auth0`, `Ory`, `Anonymous`, and writing your own.
+- [Identity claims](/users/claims) — get the user's verified email and
+  name into your `User` state.
+- [Authorization](/users/authorization) — decide who may call what.
+- [Call external APIs as the user](/users/external_apis) — act on the
+  user's behalf at Google, GitHub, Slack, …
diff --git a/documentation/docs/users/providers.mdx b/documentation/docs/users/providers.mdx
new file mode 100644
index 000000000..6ec91d1de
--- /dev/null
+++ b/documentation/docs/users/providers.mdx
@@ -0,0 +1,305 @@
+# OAuth providers
+
+An **OAuth provider** is the thing that tells Reboot who a user is.
+You pass one (or one per environment) to
+[`OAuth(provider=...)`](/users/oauth); Reboot's own OAuth server does
+everything else.
+
+All of these live in `reboot.aio.auth.oauth_providers`.
+
+| Provider | Use it when |
+| --- | --- |
+| `Development()` | Local development. Shows a fake account picker; no registration anywhere. |
+| `Anonymous()` | You want no sign-in at all. Every visitor is a new person. |
+| `Google(...)` | Users sign in with Google. |
+| `GitHub(...)` | Users sign in with GitHub. |
+| `Auth0(...)` | You want several sign-in methods, or user management, behind one provider. |
+| `Ory(...)` | Same, on Ory Network or self-hosted Ory. |
+
+:::important Pick before you have production users
+Whichever you pick issues the IDs that become your
+[`User` state IDs](/users/overview#choose-your-identity-provider-deliberately).
+Each provider issues IDs in its own space, with no mapping between
+them, so switching providers once you have real users strands every
+user-keyed piece of state you have. If you expect to need several
+sign-in methods, or user management beyond a bare ID, start with a
+broker like `Auth0` or `Ory`: they let you add and change upstream
+login methods without changing the IDs your application sees.
+:::
+
+## `Development`
+
+```python
+from reboot.aio.auth.oauth_providers import Development
+
+Development(
+    # Identity claims to deliver on each sign-in (optional). See
+    # the claims below for what it can fabricate.
+    claims=["email", "name"],
+)
+```
+
+Shows a fake "pick an account" page with a handful of identities. No
+passwords, no registration, nothing to configure.
+
+Picking the same identity twice signs you in as the *same* user, so
+you can exercise returning users, multi-user behavior, and two clients
+signed in as the same person, all locally.
+
+The user IDs it issues are opaque, so do not hardcode one into
+authorization logic; read the signed-in user's ID at runtime instead,
+as described in
+[Using the signed-in user](/users/overview#using-the-signed-in-user).
+
+:::caution Development only
+`Development` authenticates nobody. Never use it as the `prod` arm of
+your selector.
+:::
+
+### Setup
+
+None.
+
+### Claims
+
+| Claim | What it holds |
+| --- | --- |
+| `email` | A made-up address for the identity. |
+| `email_verified` | Always `true`. |
+| `name` | The identity's display name. |
+
+## `Anonymous`
+
+```python
+from reboot.aio.auth.oauth_providers import Anonymous
+
+Anonymous()
+```
+
+No sign-in page at all: every visitor becomes a fresh user. Useful for
+a demo or a kiosk-style app where per-session state is all you need. A
+returning visitor is a brand-new user, with a brand-new, empty `User`,
+so nothing can outlive a session.
+
+### Setup
+
+None.
+
+### Claims
+
+None.
+
+## `Google`
+
+```python
+from reboot.aio.auth.oauth_providers import Google
+
+Google(
+    # From the Google Cloud console. Deliver both as secrets.
+    client_id=os.environ.get("GOOGLE_OAUTH_CLIENT_ID"),
+    client_secret=os.environ.get("GOOGLE_OAUTH_CLIENT_SECRET"),
+    # Identity claims to deliver on each sign-in (optional). See the
+    # claims below.
+    claims=["email", "name"],
+    # Extra OAuth scopes, so your app can call Google's APIs on the
+    # user's behalf, and whether to keep Google's tokens for that
+    # (both optional). See Call external APIs as the user.
+    scopes=["https://www.googleapis.com/auth/calendar.events"],
+    store_tokens=True,
+)
+```
+
+### Setup
+
+In the Google Cloud console, create an OAuth 2.0 Client ID of type
+"Web application" and add `<your-backend-url>/__/oauth/callback` to
+its authorized redirect URIs. Deliver the client ID and secret as
+[secrets](/secrets).
+
+### Claims
+
+| Claim | What it holds |
+| --- | --- |
+| `email` | The account's email address. |
+| `email_verified` | Whether Google has verified that address. |
+| `name` | Full name. |
+| `given_name` | First name. |
+| `family_name` | Last name. |
+| `picture` | URL of the profile picture. |
+| `locale` | The account's locale, e.g. `en`. |
+| `profile` | URL of the profile page. |
+
+## `GitHub`
+
+```python
+from reboot.aio.auth.oauth_providers import GitHub
+
+GitHub(
+    # From the app's page in GitHub's developer settings. Deliver both
+    # as secrets.
+    client_id=os.environ.get("GITHUB_OAUTH_CLIENT_ID"),
+    client_secret=os.environ.get("GITHUB_OAUTH_CLIENT_SECRET"),
+    # Identity claims to deliver on each sign-in (optional). See the
+    # claims below.
+    claims=["email"],
+    # Extra OAuth scopes, so your app can call GitHub's API on the
+    # user's behalf, and whether to keep GitHub's tokens for that
+    # (both optional). See Call external APIs as the user.
+    scopes=["repo"],
+    store_tokens=True,
+)
+```
+
+### Setup
+
+Register an OAuth App (or a GitHub App) in GitHub's developer settings
+and set its authorization callback URL to
+`<your-backend-url>/__/oauth/callback`. Deliver the client ID and
+secret as [secrets](/secrets).
+
+### Claims
+
+| Claim | What it holds |
+| --- | --- |
+| `email` | The account's primary email address, once GitHub has verified it. |
+| `email_verified` | `true` whenever `email` is delivered. |
+
+## `Auth0`
+
+```python
+from reboot.aio.auth.oauth_providers import Auth0
+
+Auth0(
+    # Your Auth0 tenant, e.g. "your-tenant.us.auth0.com".
+    domain=os.environ.get("AUTH0_DOMAIN"),
+    # From the application's settings in the Auth0 dashboard. Deliver
+    # both as secrets.
+    client_id=os.environ.get("AUTH0_CLIENT_ID"),
+    client_secret=os.environ.get("AUTH0_CLIENT_SECRET"),
+    # Identity claims to deliver on each sign-in (optional). See the
+    # claims below.
+    claims=["email", "name"],
+    # Extra OAuth scopes, so your app can call Auth0's APIs on the
+    # user's behalf, and whether to keep Auth0's tokens for that
+    # (both optional). See Call external APIs as the user.
+    scopes=[],
+    store_tokens=False,
+)
+```
+
+One Auth0 application lets people sign in through any connection you
+enable in the Auth0 dashboard — Google, GitHub, username and password,
+enterprise SSO — and your application sees one provider.
+
+### Setup
+
+Register a "Regular Web Application" in Auth0 and add
+`<your-backend-url>/__/oauth/callback` to its allowed callback URLs.
+Deliver the client ID and secret as [secrets](/secrets).
+
+### Claims
+
+Which of these are populated depends on the connection the person
+signed in through.
+
+| Claim | What it holds |
+| --- | --- |
+| `email` | The user's email address. |
+| `email_verified` | Whether the connection has verified that address. |
+| `name` | Full name. |
+| `given_name` | First name. |
+| `family_name` | Last name. |
+| `middle_name` | Middle name. |
+| `nickname` | Nickname. |
+| `picture` | URL of the profile picture. |
+| `updated_at` | When the profile was last updated. |
+
+## `Ory`
+
+```python
+from reboot.aio.auth.oauth_providers import Ory
+
+Ory(
+    # Your Ory project, e.g. "your-slug.projects.oryapis.com".
+    domain=os.environ.get("ORY_DOMAIN"),
+    # From the OAuth2 client you created in the project. Deliver both
+    # as secrets.
+    client_id=os.environ.get("ORY_CLIENT_ID"),
+    client_secret=os.environ.get("ORY_CLIENT_SECRET"),
+    # Identity claims to deliver on each sign-in (optional). See the
+    # claims below.
+    claims=["email", "name"],
+    # Shared secret for an Ory Action that tells Reboot when a user
+    # edits their profile (optional; requires `claims`). See Keeping
+    # claims fresh with Ory.
+    webhook_secret=os.environ.get("ORY_WEBHOOK_SECRET"),
+    # Where the browser is sent for the authorization request when it
+    # reaches Ory at a different origin than your server does
+    # (optional). In local development, typically an `ory tunnel`.
+    browser_facing_url="http://localhost:4000",
+    # Extra OAuth scopes, so your app can call Ory's APIs on the
+    # user's behalf, and whether to keep Ory's tokens for that (both
+    # optional). See Call external APIs as the user.
+    scopes=[],
+    store_tokens=False,
+)
+```
+
+Works with an Ory Network project or a self-hosted Ory deployment.
+Like `Auth0`, it lets people sign in through whichever methods the
+project enables, and your application sees one provider.
+
+### Setup
+
+Create an OAuth2 client in the Ory project with the authorization-code
+grant, add `<your-backend-url>/__/oauth/callback` to its redirect
+URIs, and make sure it is allowed to request the scopes your claims
+need. Deliver the client ID and secret as [secrets](/secrets). To keep
+claims current between sign-ins, also configure the Ory Action
+described in
+[Keeping claims fresh with Ory](/users/claims#keeping-claims-fresh-with-ory).
+
+### Claims
+
+Which of these are populated depends on the project's identity schema.
+
+| Claim | What it holds |
+| --- | --- |
+| `email` | The identity's email address. |
+| `email_verified` | Whether Ory has verified that address. |
+| `name` | Full name. |
+| `given_name` | First name. |
+| `family_name` | Last name. |
+| `username` | The username. |
+| `website` | URL of the identity's website. |
+| `updated_at` | When the identity was last updated. |
+
+## Writing your own provider
+
+If none of the above fits — your users live in a self-hosted Keycloak,
+an internal SSO, or an identity provider no broker covers — subclass
+`RegisteredOAuthProvider` and pass an instance in the same `dev=` /
+`prod=` arms. You implement two methods; Reboot's OAuth server does
+the rest, including `state` verification, PKCE, and minting your
+application's own tokens:
+
+- `authorization_url(state, redirect_uri)` — build the identity
+  provider's authorize URL, passing `state` and `redirect_uri` through
+  verbatim.
+- `exchange_code(code, redirect_uri)` — exchange the code at the
+  identity provider's token endpoint and return an `ExchangeResult`
+  carrying the user's ID (and, optionally, their tokens and
+  [claims](/users/claims)).
+
+You can also override `validate()` to fail fast on missing
+configuration, and `mount_routes()` to add provider-specific HTTP
+routes.
+
+:::important
+The user ID you return must be **stable**: the same person must get
+the same ID on every sign-in. An account ID qualifies; an email
+address does not, because people change theirs. That ID becomes the
+state ID of their `User`, so the
+[namespace-permanence warning](/users/overview#choose-your-identity-provider-deliberately)
+applies to your provider too.
+:::
diff --git a/documentation/docs/users/tokens.mdx b/documentation/docs/users/tokens.mdx
new file mode 100644
index 000000000..da0e80689
--- /dev/null
+++ b/documentation/docs/users/tokens.mdx
@@ -0,0 +1,294 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Bearer tokens
+
+Reboot authenticates calls with the standard
+`Authorization: Bearer` header. When you configure
+[`oauth=`](/users/oauth), Reboot mints those tokens and the generated
+clients attach them for you, so there is nothing to do.
+
+There are two situations in which you manage bearer tokens yourself
+instead of Reboot doing it all for you: attaching a token by hand
+(from a script, a server-to-server call, or a test), and accepting
+tokens that come from somewhere other than Reboot's `OAuth` server.
+This page covers both.
+
+## Attaching a token
+
+### From within your application
+
+To carry a bearer token on every call to a particular instance,
+pass it to `ref()`:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+```py
+from_account = Account.ref(
+    request.from_account_id,
+    bearer_token=bearer_token,
+)
+```
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+```ts
+const fromAccount = Account.ref(request.fromAccountId, { bearerToken });
+```
+  </TabItem>
+</Tabs>
+
+You can also pass it as an option when doing
+[explicit construction](/call/overview#explicit-construction):
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../tests/reboot/auth_tests.py&lines=399-403) -->
+<!-- The below code snippet is automatically added from ../../../tests/reboot/auth_tests.py -->
+
+```py
+bank, _ = await Bank.create(
+    context,
+    SINGLETON_BANK_ID,
+    Options(bearer_token=VALID_JWT),
+)
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+```ts
+const [bank] = await Bank.create(
+  context,
+  SINGLETON_BANK_ID,
+  {},
+  { bearerToken: VALID_JWT }
+);
+```
+  </TabItem>
+</Tabs>
+
+### From an `ExternalContext`
+
+To carry a token on every call made from an
+[`ExternalContext`](/call/from_outside_your_app):
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+  ```py
+  context = ExternalContext(
+      name='Example',
+      url='http://localhost:9991',
+      bearer_token=token,
+  )
+  ```
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+  ```typescript
+  const context = new ExternalContext({
+    name: "Example",
+    url: "http://localhost:9991",
+    bearerToken: token,
+  });
+  ```
+  </TabItem>
+</Tabs>
+
+### From React
+
+When you use Reboot's own sign-in, the token is handled for you:
+[`useSignIn()`](/surfaces/web#signing-in) establishes the session and
+the provider attaches the bearer. If the token comes from somewhere
+else, though, set it yourself:
+
+```tsx
+import { useRebootClient } from "@reboot-dev/reboot-react";
+
+const { setBearerToken } = useRebootClient();
+
+setBearerToken(token);
+```
+
+To start out with a token you already have, pass it to
+`RebootClientProvider` instead:
+
+```tsx
+<RebootClientProvider url={url} token={token}>
+  <App />
+</RebootClientProvider>
+```
+
+### From `initialize`
+
+An [`initialize` function](/implement/application#initialize-functions)
+runs with application-internal privileges by default. To have its
+calls authenticated as a particular caller instead, give
+`Application` the token to use:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+  ```py
+  application = Application(
+      servicers=[...],
+      initialize=initialize,
+      initialize_bearer_token=os.environ.get("INITIALIZE_BEARER_TOKEN"),
+  )
+  ```
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+  ```typescript
+  new Application({
+    servicers: [...],
+    initialize,
+    initializeBearerToken: process.env.INITIALIZE_BEARER_TOKEN,
+  }).run();
+  ```
+  </TabItem>
+</Tabs>
+
+## Verifying tokens yourself
+
+The `OAuth` server verifies the tokens it minted. To accept tokens
+minted by something else — an existing identity provider, an API-key
+scheme of your own, a legacy service — supply a `TokenVerifier`.
+
+Set it on your [`Application`](/implement/application):
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+  ```py
+  async def main():
+      application = Application(
+          servicers=[...],
+          token_verifier=MyTokenVerifier(...),
+      )
+      await application.run()
+  ```
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+  ```typescript
+  new Application({
+    servicers: [...],
+    ...,
+    tokenVerifier: new MyTokenVerifier(...),
+  }).run();
+  ```
+  </TabItem>
+
+</Tabs>
+
+In unit tests, hand that same `Application` to the test harness's
+`up`:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+  ```py
+  await self.rbt.up(
+      Application(
+          servicers=[...],
+          token_verifier=MyTokenVerifier(...),
+      )
+  )
+  ```
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+  ```typescript
+  await rbt.up(
+    new Application({
+      servicers: [...],
+      tokenVerifier: new MyTokenVerifier(...),
+    })
+  );
+  ```
+  </TabItem>
+</Tabs>
+
+The interface has a single method. It receives the token from the
+`Authorization: Bearer` header and returns an `Auth` object when the
+token is valid:
+
+<Tabs groupId="language">
+  <TabItem value="python" label="Python">
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/aio/auth/token_verifiers.py&lines=26-31) -->
+<!-- The below code snippet is automatically added from ../../../reboot/aio/auth/token_verifiers.py -->
+
+```py
+@abstractmethod
+async def verify_token(
+    self,
+    context: ReaderContext,
+    token: Optional[str],
+) -> VerifyTokenResult:
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/nodejs/index.ts&lines=668-671) -->
+<!-- The below code snippet is automatically added from ../../../reboot/nodejs/index.ts -->
+
+```ts
+abstract verifyToken(
+  context: ReaderContext,
+  token?: string
+): Promise<Auth | null>;
+```
+
+<!-- MARKDOWN-AUTO-DOCS:END -->
+  </TabItem>
+</Tabs>
+
+Set any properties you like on the returned `Auth`
+([Python](https://github.com/reboot-dev/reboot/blob/main/reboot/aio/auth/__init__.py#L45),
+[TypeScript](https://github.com/reboot-dev/reboot/blob/main/reboot/nodejs/index.ts#L618))
+for your [authorizers](/users/authorization) to consume. The `user_id`
+(Python) / `userId` (TypeScript) property is special: it is what marks
+this as a valid user, and what `state_id_is_user_id` and the `User`
+default compare against.
+
+:::tip
+
+**Token verification does not necessarily mean user authentication!**
+
+Depending on where and how tokens are generated, a valid token may
+only mean "this is a valid user *of that provider*" — not "this is a
+user of *your* application". Read your provider's documentation
+carefully, and make sure you are validating tokens in a way that is
+specific to your application (audience checks, issuer checks, and so
+on).
+
+:::
+
+## Combining a verifier with Reboot's OAuth
+
+`oauth=` and `token_verifier=` can be set together. The `OAuth`
+server's verifier runs first: a token it minted is accepted, or
+rejected if it has expired; any other token is passed on to your
+`TokenVerifier`.
+
+Tokens your `TokenVerifier` accepts authenticate Reboot RPCs. They do
+not authenticate the [`/mcp` endpoint](/surfaces/ai_chat), because
+MCP clients sign in through OAuth rather than presenting a bearer
+token of their own, so that endpoint takes only tokens the `OAuth`
+server minted.
+
+## Third-party identity providers without Reboot's OAuth server
+
+If you would rather not use `oauth=` at all — for example because your
+users already sign in through an existing system that hands your front
+end an access token — the integration is:
+
+1. Implement a `TokenVerifier` that validates that provider's access
+   tokens and produces `Auth` objects with the right `user_id`.
+2. Provide [authorizer rules](/users/authorization) for your
+   servicers.
+
+Note that [`User` auto-construction](/users/overview) needs `oauth=`:
+a `token_verifier=` authenticates requests but never constructs users,
+so an application with a `User` type and no `oauth=` refuses to start.
diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts
index 3d4462ed6..a96ea2546 100644
--- a/documentation/docusaurus.config.ts
+++ b/documentation/docusaurus.config.ts
@@ -11,7 +11,8 @@ import { themes as prismThemes } from "prism-react-renderer";
 /** @type {import('@docusaurus/types').Config} */
 const config: Config = {
   title: "Reboot Docs",
-  tagline: "Distributed Data - Batteries Included - Learn How!",
+  tagline:
+    "A full-stack framework for the AI era: durable applications, correct concurrency, retry safety, and signed-in users.",
   favicon: "img/favicon.svg",
 
   // Set the production url of your site here
@@ -36,7 +37,108 @@ const config: Config = {
     locales: ["en"],
   },
 
-  plugins: [tailwindPlugin],
+  plugins: [
+    tailwindPlugin,
+    [
+      "@docusaurus/plugin-client-redirects",
+      {
+        // Pages that this site published under an older URL. Reboot's
+        // own source — generated servicer boilerplate, example
+        // READMEs, error messages — links to some of these, as do
+        // third parties, so they keep resolving.
+        redirects: [
+          { from: "/ai_chat_apps/what_is", to: "/surfaces/ai_chat" },
+          { from: "/learn_more/mcp_apps", to: "/surfaces/ai_chat" },
+          {
+            from: "/learn_more/implement/ui_methods",
+            to: "/surfaces/ui_methods",
+          },
+          {
+            from: "/ai_chat_apps/get_started",
+            to: "/get_started/claude_code",
+          },
+          { from: "/get_started/quickstart", to: "/get_started/claude_code" },
+          {
+            from: [
+              "/ai_chat_apps/get_started_claude_code",
+              "/full_stack_apps/get_started_claude_code",
+            ],
+            to: "/get_started/claude_code",
+          },
+          {
+            from: [
+              "/ai_chat_apps/get_started_codex",
+              "/full_stack_apps/get_started_codex",
+            ],
+            to: "/get_started/codex",
+          },
+          {
+            from: ["/ai_chat_apps/examples", "/full_stack_apps/examples"],
+            to: "/get_started/examples",
+          },
+          { from: "/full_stack_apps/python", to: "/get_started/python" },
+          {
+            from: "/full_stack_apps/typescript",
+            to: "/get_started/typescript",
+          },
+          { from: "/full_stack_apps/react", to: "/get_started/react" },
+          { from: "/learn_more/define/overview", to: "/define/overview" },
+          { from: "/learn_more/define/methods", to: "/define/methods" },
+          { from: "/learn_more/define/pydantic", to: "/define/pydantic" },
+          { from: "/learn_more/define/zod", to: "/define/zod" },
+          { from: "/learn_more/define/protobuf", to: "/define/overview" },
+          { from: "/define/protobuf", to: "/define/overview" },
+          {
+            from: "/learn_more/implement/servicers",
+            to: "/implement/servicers",
+          },
+          { from: "/learn_more/implement/readers", to: "/implement/readers" },
+          { from: "/learn_more/implement/writers", to: "/implement/writers" },
+          {
+            from: "/learn_more/implement/transactions",
+            to: "/implement/transactions",
+          },
+          {
+            from: "/learn_more/implement/workflows",
+            to: "/implement/workflows",
+          },
+          {
+            from: "/learn_more/applications",
+            to: "/implement/application",
+          },
+          { from: "/learn_more/call/overview", to: "/call/overview" },
+          { from: "/learn_more/call/from_react", to: "/call/from_react" },
+          {
+            from: "/learn_more/call/from_within_your_app",
+            to: "/call/from_within_your_app",
+          },
+          {
+            from: "/learn_more/call/from_outside_your_app",
+            to: "/call/from_outside_your_app",
+          },
+          { from: "/learn_more/call/via_http", to: "/call/via_http" },
+          {
+            from: "/learn_more/call/from_mcp_client",
+            to: "/call/from_mcp_client",
+          },
+          { from: "/learn_more/auth", to: "/users/authorization" },
+          {
+            from: "/learn_more/identity_and_external_apis",
+            to: "/users/external_apis",
+          },
+          { from: "/learn_more/tasks", to: "/tasks" },
+          { from: "/learn_more/side_effects", to: "/side_effects" },
+          { from: "/learn_more/idempotency", to: "/idempotency" },
+          { from: "/learn_more/errors", to: "/errors" },
+          { from: "/learn_more/agents", to: "/agents" },
+          { from: "/learn_more/secrets", to: "/secrets" },
+          { from: "/learn_more/testing", to: "/testing" },
+          { from: "/learn_more/nonlocal", to: "/nonlocal" },
+          { from: "/tools/cli", to: "/rbt_cli" },
+        ],
+      },
+    ],
+  ],
 
   presets: [
     [
diff --git a/documentation/package-lock.json b/documentation/package-lock.json
index 212ee0720..cbee913aa 100644
--- a/documentation/package-lock.json
+++ b/documentation/package-lock.json
@@ -9,6 +9,7 @@
       "version": "0.0.0",
       "dependencies": {
         "@docusaurus/core": "3.10.1",
+        "@docusaurus/plugin-client-redirects": "^3.10.1",
         "@docusaurus/plugin-google-gtag": "^3.10.1",
         "@docusaurus/preset-classic": "3.10.1",
         "@mdx-js/react": "^3.1.0",
@@ -3751,6 +3752,30 @@
         "react-dom": "*"
       }
     },
+    "node_modules/@docusaurus/plugin-client-redirects": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-3.10.1.tgz",
+      "integrity": "sha512-LHgd+YDvkhfOHMAE6XtUng3DQNzVM765RqVRrMJgHtzAvfopQhY6ieprqjxDVBdv21cLma6I0jHr+YCZH8fL9A==",
+      "license": "MIT",
+      "dependencies": {
+        "@docusaurus/core": "3.10.1",
+        "@docusaurus/logger": "3.10.1",
+        "@docusaurus/utils": "3.10.1",
+        "@docusaurus/utils-common": "3.10.1",
+        "@docusaurus/utils-validation": "3.10.1",
+        "eta": "^2.2.0",
+        "fs-extra": "^11.1.1",
+        "lodash": "^4.17.21",
+        "tslib": "^2.6.0"
+      },
+      "engines": {
+        "node": ">=20.0"
+      },
+      "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/@docusaurus/plugin-content-blog": {
       "version": "3.10.1",
       "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-3.10.1.tgz",
@@ -21902,6 +21927,22 @@
         "react-loadable": "npm:@docusaurus/react-loadable@6.0.0"
       }
     },
+    "@docusaurus/plugin-client-redirects": {
+      "version": "3.10.1",
+      "resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-3.10.1.tgz",
+      "integrity": "sha512-LHgd+YDvkhfOHMAE6XtUng3DQNzVM765RqVRrMJgHtzAvfopQhY6ieprqjxDVBdv21cLma6I0jHr+YCZH8fL9A==",
+      "requires": {
+        "@docusaurus/core": "3.10.1",
+        "@docusaurus/logger": "3.10.1",
+        "@docusaurus/utils": "3.10.1",
+        "@docusaurus/utils-common": "3.10.1",
+        "@docusaurus/utils-validation": "3.10.1",
+        "eta": "^2.2.0",
+        "fs-extra": "^11.1.1",
+        "lodash": "^4.17.21",
+        "tslib": "^2.6.0"
+      }
+    },
     "@docusaurus/plugin-content-blog": {
       "version": "3.10.1",
       "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-3.10.1.tgz",
diff --git a/documentation/package.json b/documentation/package.json
index e620f4676..c395e66d3 100644
--- a/documentation/package.json
+++ b/documentation/package.json
@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@docusaurus/core": "3.10.1",
+    "@docusaurus/plugin-client-redirects": "^3.10.1",
     "@docusaurus/plugin-google-gtag": "^3.10.1",
     "@docusaurus/preset-classic": "3.10.1",
     "@mdx-js/react": "^3.1.0",
diff --git a/documentation/sidebars.js b/documentation/sidebars.js
index 44ab122e9..6739aa9a3 100644
--- a/documentation/sidebars.js
+++ b/documentation/sidebars.js
@@ -22,117 +22,185 @@ const sidebars = {
     {
       type: "category",
       collapsed: false,
-      label: "Full-stack apps",
+      label: "Get started",
       items: [
         {
           type: "doc",
-          id: "full_stack_apps/get_started_claude_code",
-          label: "Get Started (with Claude Code)",
+          id: "get_started/claude_code",
+          label: "Build with Claude Code",
         },
         {
           type: "doc",
-          id: "full_stack_apps/get_started_codex",
-          label: "Get Started (with Codex)",
+          id: "get_started/codex",
+          label: "Build with Codex",
         },
         {
           type: "category",
           collapsed: true,
-          label: "Get Started (hand-written)",
+          label: "Step by step",
           items: [
-            "full_stack_apps/typescript",
-            "full_stack_apps/python",
-            "full_stack_apps/react",
+            {
+              type: "doc",
+              id: "get_started/python",
+              label: "Python backend",
+            },
+            {
+              type: "doc",
+              id: "get_started/typescript",
+              label: "TypeScript backend",
+            },
+            {
+              type: "doc",
+              id: "get_started/react",
+              label: "React frontend",
+            },
           ],
         },
-        "full_stack_apps/examples",
+        {
+          type: "doc",
+          id: "get_started/examples",
+          label: "Examples",
+        },
       ],
     },
+    {
+      type: "doc",
+      id: "concepts",
+      label: "How Reboot works",
+    },
     {
       type: "category",
       collapsed: true,
-      label: "AI Chat Apps",
+      label: "Users and auth",
       items: [
-        "ai_chat_apps/what_is",
         {
           type: "doc",
-          id: "ai_chat_apps/get_started_claude_code",
-          label: "Get Started (with Claude Code)",
+          id: "users/overview",
+          label: "Users and sign-in",
         },
         {
           type: "doc",
-          id: "ai_chat_apps/get_started_codex",
-          label: "Get Started (with Codex)",
+          id: "users/oauth",
+          label: "Configure OAuth",
         },
         {
           type: "doc",
-          id: "ai_chat_apps/get_started",
-          label: "Get Started (hand-written)",
+          id: "users/providers",
+          label: "OAuth providers",
         },
         {
           type: "doc",
-          id: "ai_chat_apps/examples",
-          label: "Examples",
+          id: "users/claims",
+          label: "Identity claims",
+        },
+        {
+          type: "doc",
+          id: "users/authorization",
+          label: "Authorization",
+        },
+        {
+          type: "doc",
+          id: "users/tokens",
+          label: "Bearer tokens",
+        },
+        {
+          type: "doc",
+          id: "users/external_apis",
+          label: "Call external APIs as the user",
         },
       ],
     },
     {
       type: "category",
       collapsed: true,
-      label: "Learn More",
+      label: "One backend, many frontends",
       items: [
-        "learn_more/mcp_apps",
         {
-          type: "category",
-          collapsed: true,
-          label: "Define your API",
-          items: [
-            "learn_more/define/overview",
-            "learn_more/define/methods",
-            "learn_more/define/pydantic",
-            "learn_more/define/zod",
-            "learn_more/define/protobuf",
-          ],
+          type: "doc",
+          id: "surfaces/overview",
+          label: "Overview",
+        },
+        {
+          type: "doc",
+          id: "surfaces/web",
+          label: "Web apps",
+        },
+        {
+          type: "doc",
+          id: "surfaces/react_native",
+          label: "React Native apps",
         },
         {
           type: "category",
-          collapsed: true,
-          label: "Implement your API",
+          label: "AI chat apps",
+          link: { type: "doc", id: "surfaces/ai_chat" },
           items: [
-            "learn_more/implement/servicers",
-            "learn_more/implement/readers",
-            "learn_more/implement/writers",
-            "learn_more/implement/transactions",
-            "learn_more/implement/workflows",
             {
               type: "doc",
-              id: "learn_more/implement/ui_methods",
-              label: "UIs for AI Chat Apps",
+              id: "surfaces/ui_methods",
+              label: "UI methods",
             },
           ],
         },
-        "learn_more/applications",
+      ],
+    },
+    {
+      type: "category",
+      collapsed: true,
+      label: "Define your API",
+      items: [
+        "define/overview",
+        "define/methods",
+        "define/pydantic",
+        "define/zod",
+      ],
+    },
+    {
+      type: "category",
+      collapsed: true,
+      label: "Implement your API",
+      items: [
+        "implement/servicers",
+        "implement/readers",
+        "implement/writers",
+        "implement/transactions",
+        "implement/workflows",
         {
-          type: "category",
-          collapsed: true,
-          label: "Call your API",
-          items: [
-            "learn_more/call/overview",
-            "learn_more/call/from_react",
-            "learn_more/call/from_within_your_app",
-            "learn_more/call/from_outside_your_app",
-            "learn_more/call/via_http",
-            "learn_more/call/from_mcp_client",
-          ],
+          type: "doc",
+          id: "implement/application",
+          label: "Run your application",
         },
-        "learn_more/testing",
-        "learn_more/auth",
-        "learn_more/identity_and_external_apis",
-        "learn_more/secrets",
-        "learn_more/errors",
-        "learn_more/tasks",
-        "learn_more/side_effects",
-        "learn_more/idempotency",
-        "learn_more/agents",
+      ],
+    },
+    {
+      type: "category",
+      collapsed: true,
+      label: "Call your API",
+      items: [
+        "call/overview",
+        "call/from_react",
+        "call/from_within_your_app",
+        "call/from_outside_your_app",
+        "call/via_http",
+        "call/from_mcp_client",
+      ],
+    },
+    {
+      type: "category",
+      collapsed: true,
+      label: "Going further",
+      items: [
+        "tasks",
+        "side_effects",
+        {
+          type: "doc",
+          id: "agents",
+          label: "Agents inside your app",
+        },
+        "idempotency",
+        "errors",
+        "secrets",
+        "testing",
       ],
     },
     {
@@ -152,25 +220,46 @@ const sidebars = {
       ],
     },
     {
-      type: "doc",
-      id: "develop_locally",
-      label: "Develop locally",
-    },
-    {
-      type: "doc",
-      id: "upgrade",
-      label: "Upgrade Reboot",
-    },
-    "tools/cli",
-    {
-      type: "doc",
-      id: "deploy_on_your_own",
-      label: "Deploy on your own",
-    },
-    {
-      type: "doc",
-      id: "deploy_on_reboot_cloud",
-      label: "Deploy on Reboot Cloud",
+      type: "category",
+      collapsed: true,
+      label: "Develop and deploy",
+      items: [
+        {
+          type: "doc",
+          id: "develop_locally",
+          label: "Develop locally",
+        },
+        {
+          type: "doc",
+          id: "nonlocal",
+          label: "Non-local development",
+        },
+        {
+          type: "doc",
+          id: "rbt_cli",
+          label: "The rbt CLI",
+        },
+        {
+          type: "doc",
+          id: "deploy_on_reboot_cloud",
+          label: "Deploy on Reboot Cloud",
+        },
+        {
+          type: "doc",
+          id: "deploy_on_your_own",
+          label: "Deploy on your own",
+        },
+        {
+          type: "doc",
+          id: "upgrade",
+          label: "Upgrade Reboot",
+        },
+        {
+          type: "doc",
+          id: "known_issues",
+          label: "Known issues",
+        },
+      ],
     },
     // {
     //   type: "category",
@@ -178,12 +267,6 @@ const sidebars = {
     //   items: ["deploy_operate/import_export"],
     // },
     // TODO: #3363.
-
-    {
-      type: "doc",
-      id: "known_issues",
-      label: "Known issues",
-    },
   ],
 };
 
diff --git a/reboot/aio/auth/authorizers.py b/reboot/aio/auth/authorizers.py
index 9c4c6895a..9250b22fb 100644
--- a/reboot/aio/auth/authorizers.py
+++ b/reboot/aio/auth/authorizers.py
@@ -390,9 +390,9 @@ async def authorize(
                 f"*** {self._state_name}.{method_name.split('.')[-1]} IS "
                 "MISSING AUTHORIZATION *** Calls to this method are ONLY "
                 "ALLOWED during development and will be DENIED in "
-                f"production. See {DOCS_BASE_URL}/learn_more/auth#default-authorizer "
-                "for more details. Will silence this message for the next 1 "
-                "minute."
+                f"production. See {DOCS_BASE_URL}/users/authorization"
+                "#relaxed-during-development for more details. Will "
+                "silence this message for the next 1 minute."
             )
         )
 
diff --git a/reboot/web/index.ts b/reboot/web/index.ts
index cac6e9a99..680b135b5 100644
--- a/reboot/web/index.ts
+++ b/reboot/web/index.ts
@@ -571,7 +571,9 @@ export class WebSockets {
             "number of concurrent streams. Reboot uses HTTP/2 by default " +
             "when you use TLS. You should definitely use TLS when you deploy " +
             "your application in the cloud, but you can also use TLS when " +
-            "running `rbt dev`, please see the documentation for how to do so."
+            "running `rbt dev`. See " +
+            "https://docs.reboot.dev/rbt_cli#bring-your-own-certificate-with-rbt-dev-run " +
+            "for how to do so."
         );
       }
     });
@@ -927,7 +929,7 @@ function trackFetch(url: URL) {
           )} are either long-running or ` +
           `queued because your browser limits the total number of simultaneous connections ` +
           `to the same host (${host}). You can solve this by ensuring you use HTTP/2 which ` +
-          `requires TLS. See https://docs.reboot.dev/tools/cli/#bring-your-own-certificate-with-rbt-dev-run ` +
+          `requires TLS. See https://docs.reboot.dev/rbt_cli#bring-your-own-certificate-with-rbt-dev-run ` +
           `for details on how to use TLS with 'rbt dev' (which works similarly for 'rbt serve').`
       );
 
diff --git a/tests/reboot/documentation/BUILD.bazel b/tests/reboot/documentation/BUILD.bazel
index 2d4c5e10a..2af66b623 100644
--- a/tests/reboot/documentation/BUILD.bazel
+++ b/tests/reboot/documentation/BUILD.bazel
@@ -459,6 +459,97 @@ py_test(
     ],
 )
 
+# The todo-list example the users docs pull from: a `User` that is the
+# person (profile plus the lists they own), and the `TodoList` they
+# create. Same layout as the `ai_chat_counter` example above.
+py_library(
+    name = "todos_py",
+    srcs = ["todos.py"],
+    deps = ["//reboot:api_py"],
+)
+
+py_reboot_library_from_pydantic(
+    name = "todos_py_reboot",
+    py_deps = [":todos_py"],
+    pydantic = ":todos.py",
+)
+
+py_library(
+    name = "todos_servicer_py",
+    srcs = [
+        "backend/src/servicers/__init__.py",
+        "backend/src/servicers/todos.py",
+    ],
+    imports = ["backend/src"],
+    deps = [
+        ":todos_py",
+        ":todos_py_reboot",
+    ],
+)
+
+# Exercises first-sign-in seeding (`User.create`), claims delivery
+# (`User.set_claims`), the `User`-as-entry-point methods, and the
+# owner-only authorizer.
+py_test(
+    name = "test_todos_py",
+    srcs = ["test_todos.py"],
+    imports = ["backend/src"],
+    main = "test_todos.py",
+    deps = [
+        ":todos_servicer_py",
+        "//reboot/aio:applications_py",
+        "//reboot/aio:tests_py",
+    ],
+)
+
+js_reboot_react_library_from_pydantic(
+    name = "todos_js_reboot_react",
+    package_json = ":package.json",
+    pydantic = ":todos.py",
+)
+
+# Type-checks the `useSignIn()` / `useUser()` entrypoint the users docs
+# show, against the hooks generated from `todos.py`.
+ts_project(
+    name = "todos_main_ts",
+    srcs = [
+        "get_started_env.d.ts",
+        "todos_main.tsx",
+        ":package.json",
+    ],
+    declaration = True,
+    tsconfig = {
+        "compilerOptions": {
+            "baseUrl": ".",
+            "jsx": "react-jsx",
+            "lib": [
+                "ES2022",
+                "DOM",
+                "DOM.Iterable",
+            ],
+            "module": "esnext",
+            "moduleResolution": "bundler",
+            "paths": {
+                "@api/todos/v1/todos_rbt_react": [
+                    "./todos_zod_rbt_react",
+                ],
+            },
+            "skipLibCheck": True,
+            "strict": True,
+            "target": "es2022",
+        },
+    },
+    deps = [
+        ":todos_js_reboot_react",
+        "//:node_modules/@reboot-dev/reboot-react",
+        "//:node_modules/@reboot-dev/reboot-web",
+        "//:node_modules/@types/react",
+        "//:node_modules/react",
+        "//:node_modules/react-dom",
+        "//:node_modules/zod",
+    ],
+)
+
 js_reboot_react_library_from_pydantic(
     name = "ai_chat_counter_js_reboot_react",
     package_json = ":package.json",
diff --git a/tests/reboot/documentation/backend/src/servicers/todos.py b/tests/reboot/documentation/backend/src/servicers/todos.py
new file mode 100644
index 000000000..1665ca5d6
--- /dev/null
+++ b/tests/reboot/documentation/backend/src/servicers/todos.py
@@ -0,0 +1,133 @@
+# backend/src/servicers/todos.py
+from rbt.v1alpha1.errors_pb2 import Ok, PermissionDenied, Unauthenticated
+from reboot.aio.auth.authorizers import Authorizer, allow_if, is_app_internal
+from reboot.aio.contexts import (
+    ReaderContext,
+    TransactionContext,
+    WriterContext,
+)
+from tests.reboot.documentation.todos import (
+    AddTodoRequest,
+    CreateTodoListRequest,
+    CreateTodoListResponse,
+    InitializeTodoListRequest,
+    ListTodoListsResponse,
+    ProfileResponse,
+    TodoListSummary,
+    TodosResponse,
+)
+from tests.reboot.documentation.todos_rbt import TodoList, User
+from typing import Optional
+
+
+def _caller_is_owner(
+    *,
+    context: ReaderContext,
+    state: Optional[TodoList.State],
+    **kwargs,
+):
+    """Allow when the caller's `user_id` matches the list's recorded
+    `owner_id`. A not-yet-constructed list (`state is None`) falls
+    through to deny."""
+    if context.auth is None or not context.auth.user_id:
+        return Unauthenticated()
+    if state is not None and context.auth.user_id == state.owner_id:
+        return Ok()
+    return PermissionDenied()
+
+
+class UserServicer(User.Servicer):
+    """The signed-in person: their profile, and the todo lists they
+    own."""
+
+    async def create(
+        self,
+        context: TransactionContext,
+    ) -> None:
+        """Runs once, when a person signs in for the first time: give
+        them a list to start with."""
+        todo_list, _ = await TodoList.create(
+            context,
+            title="Getting started",
+            owner_id=context.state_id,
+        )
+        await todo_list.add(context, todo="Add your first todo")
+        self.state.todo_lists[todo_list.state_id] = "Getting started"
+
+    async def set_claims(
+        self,
+        context: TransactionContext,
+        request: User.SetClaimsRequest,
+    ) -> None:
+        """Runs on every sign-in with the identity provider's verified
+        claims, which are the complete, current set: derive all
+        claim-backed state from them rather than merging."""
+        self.state.name = request.claims.get("name", "")
+        self.state.email = request.claims.get("email", "")
+
+    async def profile(
+        self,
+        context: ReaderContext,
+    ) -> ProfileResponse:
+        return ProfileResponse(name=self.state.name, email=self.state.email)
+
+    async def create_todo_list(
+        self,
+        context: TransactionContext,
+        request: CreateTodoListRequest,
+    ) -> CreateTodoListResponse:
+        """Create a list owned by the signed-in person and remember it
+        on their `User`."""
+        todo_list, _ = await TodoList.create(
+            context,
+            title=request.title,
+            owner_id=context.state_id,
+        )
+        self.state.todo_lists[todo_list.state_id] = request.title
+        return CreateTodoListResponse(todo_list_id=todo_list.state_id)
+
+    async def list_todo_lists(
+        self,
+        context: ReaderContext,
+    ) -> ListTodoListsResponse:
+        return ListTodoListsResponse(
+            todo_lists=[
+                TodoListSummary(todo_list_id=todo_list_id, title=title)
+                for todo_list_id, title in self.state.todo_lists.items()
+            ]
+        )
+
+
+class TodoListServicer(TodoList.Servicer):
+    """One todo list, readable and writable by its owner only."""
+
+    def authorizer(self) -> Authorizer:
+        return TodoList.Authorizer(
+            # `create` is restricted to trusted app code and records
+            # the list's owner; every other method is restricted to
+            # that owner (or, again, to trusted app code).
+            create=allow_if(all=[is_app_internal]),
+            add=allow_if(any=[_caller_is_owner, is_app_internal]),
+            todos=allow_if(any=[_caller_is_owner, is_app_internal]),
+        )
+
+    async def create(
+        self,
+        context: WriterContext,
+        request: InitializeTodoListRequest,
+    ) -> None:
+        self.state.title = request.title
+        self.state.owner_id = request.owner_id
+
+    async def add(
+        self,
+        context: WriterContext,
+        request: AddTodoRequest,
+    ) -> None:
+        self.state.todos.append(request.todo)
+
+    async def todos(
+        self,
+        context: ReaderContext,
+    ) -> TodosResponse:
+        return TodosResponse(title=self.state.title, todos=self.state.todos)
diff --git a/tests/reboot/documentation/test_todos.py b/tests/reboot/documentation/test_todos.py
new file mode 100644
index 000000000..edecf09fd
--- /dev/null
+++ b/tests/reboot/documentation/test_todos.py
@@ -0,0 +1,109 @@
+import unittest
+from reboot.aio.aborted import Aborted
+from reboot.aio.applications import Application
+from reboot.aio.tests import Reboot
+from servicers.todos import TodoListServicer, UserServicer
+from tests.reboot.documentation.todos_rbt import TodoList, User
+
+_ALICE = "alice"
+
+
+class TodosTest(unittest.IsolatedAsyncioTestCase):
+    """Exercises the todo-list `User` example the users docs pull
+    from, so the code they show is real and tested."""
+
+    async def asyncSetUp(self) -> None:
+        self.rbt = Reboot()
+        await self.rbt.start()
+        await self.rbt.up(
+            Application(servicers=[UserServicer, TodoListServicer])
+        )
+        # A signed-in person: minting the token goes through the same
+        # code path as a real sign-in, which auto-constructs their
+        # `User` (and so runs `UserServicer.create`).
+        self.context = await self.rbt.create_external_context_as(
+            name=f"test-{self.id()}",
+            user_id=_ALICE,
+        )
+
+    async def asyncTearDown(self) -> None:
+        await self.rbt.stop()
+
+    async def test_first_sign_in_seeds_a_list_once(self) -> None:
+        # `create` ran on first sign-in and left a list behind.
+        listed = await User.ref(_ALICE).list_todo_lists(self.context)
+        self.assertEqual(
+            [todo_list.title for todo_list in listed.todo_lists],
+            ["Getting started"],
+        )
+        todos = await TodoList.ref(listed.todo_lists[0].todo_list_id
+                                  ).todos(self.context)
+        self.assertEqual(todos.todos, ["Add your first todo"])
+
+        # Signing in again finds the same `User`; `create` does not
+        # run a second time.
+        again = await self.rbt.create_external_context_as(
+            name=f"again-{self.id()}",
+            user_id=_ALICE,
+        )
+        listed = await User.ref(_ALICE).list_todo_lists(again)
+        self.assertEqual(len(listed.todo_lists), 1)
+
+    async def test_create_add_and_list(self) -> None:
+        created = await User.ref(_ALICE).create_todo_list(
+            self.context,
+            title="Groceries",
+        )
+        todo_list = TodoList.ref(created.todo_list_id)
+        await todo_list.add(self.context, todo="Milk")
+
+        todos = await todo_list.todos(self.context)
+        self.assertEqual(todos.title, "Groceries")
+        self.assertEqual(todos.todos, ["Milk"])
+
+        listed = await User.ref(_ALICE).list_todo_lists(self.context)
+        self.assertEqual(
+            sorted(todo_list.title for todo_list in listed.todo_lists),
+            ["Getting started", "Groceries"],
+        )
+
+    async def test_claims_fill_in_the_profile(self) -> None:
+        # A sign-in that delivers identity claims lands them in
+        # `UserServicer.set_claims`.
+        token = await self.rbt.make_valid_oauth_access_token(
+            user_id=_ALICE,
+            claims={
+                "name": "Alice",
+                "email": "alice@example.com"
+            },
+        )
+        context = self.rbt.create_external_context(
+            name=f"claims-{self.id()}",
+            bearer_token=token,
+        )
+        profile = await User.ref(_ALICE).profile(context)
+        self.assertEqual(profile.name, "Alice")
+        self.assertEqual(profile.email, "alice@example.com")
+
+    async def test_non_owner_cannot_read_a_list(self) -> None:
+        created = await User.ref(_ALICE).create_todo_list(
+            self.context,
+            title="Private",
+        )
+
+        # Another signed-in person, with a valid token but a different
+        # `user_id`, is refused by the `_caller_is_owner` authorizer.
+        other_context = await self.rbt.create_external_context_as(
+            name=f"other-{self.id()}",
+            user_id="bob",
+        )
+        with self.assertRaises(Aborted):
+            await TodoList.ref(created.todo_list_id).todos(other_context)
+
+        # The owner still can.
+        todos = await TodoList.ref(created.todo_list_id).todos(self.context)
+        self.assertEqual(todos.title, "Private")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/reboot/documentation/todos.py b/tests/reboot/documentation/todos.py
new file mode 100644
index 000000000..910d31afd
--- /dev/null
+++ b/tests/reboot/documentation/todos.py
@@ -0,0 +1,122 @@
+# api/todos/v1/todos.py
+from reboot.api import (
+    API,
+    Field,
+    Methods,
+    Model,
+    Reader,
+    Tool,
+    Transaction,
+    Type,
+    Writer,
+)
+
+
+class UserState(Model):
+    # The person's profile, kept current from the identity provider's
+    # verified claims on every sign-in.
+    name: str = Field(tag=1, default="")
+    email: str = Field(tag=2, default="")
+    # The todo lists this person owns: each list's state ID, and its
+    # title so the lists can be shown without a call per list.
+    todo_lists: dict[str, str] = Field(tag=3, default_factory=dict)
+
+
+class ProfileResponse(Model):
+    name: str = Field(tag=1)
+    email: str = Field(tag=2)
+
+
+class CreateTodoListRequest(Model):
+    title: str = Field(tag=1)
+
+
+class CreateTodoListResponse(Model):
+    todo_list_id: str = Field(tag=1)
+
+
+class TodoListSummary(Model):
+    todo_list_id: str = Field(tag=1)
+    title: str = Field(tag=2)
+
+
+class ListTodoListsResponse(Model):
+    todo_lists: list[TodoListSummary] = Field(tag=1, default_factory=list)
+
+
+class TodoListState(Model):
+    title: str = Field(tag=1, default="")
+    # The `user_id` of the owner, so that only they may read or change
+    # the list.
+    owner_id: str = Field(tag=2, default="")
+    todos: list[str] = Field(tag=3, default_factory=list)
+
+
+class InitializeTodoListRequest(Model):
+    title: str = Field(tag=1)
+    owner_id: str = Field(tag=2)
+
+
+class AddTodoRequest(Model):
+    todo: str = Field(tag=1)
+
+
+class TodosResponse(Model):
+    title: str = Field(tag=1)
+    todos: list[str] = Field(tag=2, default_factory=list)
+
+
+api = API(
+    User=Type(
+        state=UserState,
+        methods=Methods(
+            profile=Reader(
+                request=None,
+                response=ProfileResponse,
+                description="The signed-in user's name and email.",
+                mcp=Tool(),
+            ),
+            create_todo_list=Transaction(
+                request=CreateTodoListRequest,
+                response=CreateTodoListResponse,
+                description="Create a todo list for the signed-in "
+                "user. Returns its `todo_list_id`, which is not "
+                "human-readable but must be passed to tools that "
+                "take one.",
+                mcp=Tool(),
+            ),
+            list_todo_lists=Reader(
+                request=None,
+                response=ListTodoListsResponse,
+                description="List the signed-in user's todo lists: "
+                "`todo_list_id` and title for each.",
+                mcp=Tool(),
+            ),
+        ),
+    ),
+    TodoList=Type(
+        state=TodoListState,
+        methods=Methods(
+            create=Writer(
+                request=InitializeTodoListRequest,
+                response=None,
+                factory=True,
+                description="Create the list with a title and an "
+                "owner.",
+                mcp=None,
+            ),
+            add=Writer(
+                request=AddTodoRequest,
+                response=None,
+                description="Add a todo to the list.",
+                mcp=Tool(),
+            ),
+            todos=Reader(
+                request=None,
+                response=TodosResponse,
+                description="The list's title and its todos.",
+                mcp=Tool(),
+            ),
+        ),
+    ),
+)
diff --git a/tests/reboot/documentation/todos_main.tsx b/tests/reboot/documentation/todos_main.tsx
new file mode 100644
index 000000000..852529cbe
--- /dev/null
+++ b/tests/reboot/documentation/todos_main.tsx
@@ -0,0 +1,46 @@
+// frontend/web/src/main.tsx
+import { type UseUserApi, useUser } from "@api/todos/v1/todos_rbt_react";
+import { RebootClientProvider, useSignIn } from "@reboot-dev/reboot-react";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+// The signed-in person, or a button to become one. `useUser()` takes
+// no ID: it resolves the caller's own `User`, the instance Reboot
+// auto-constructed when they signed in.
+const Root = () => {
+  const { user, isLoading } = useUser();
+  const signIn = useSignIn();
+
+  if (isLoading) return <p>Checking session…</p>;
+  if (user === undefined) {
+    return <button onClick={() => signIn()}>Sign in</button>;
+  }
+  return <TodoLists user={user} />;
+};
+
+// Everything the app knows about this person hangs off `user`: its
+// readers are reactive hooks, its mutators are plain calls.
+const TodoLists = ({ user }: { user: UseUserApi }) => {
+  const { response } = user.useListTodoLists();
+
+  return (
+    <ul>
+      {(response?.todoLists ?? []).map((todoList) => (
+        <li key={todoList.todoListId}>{todoList.title}</li>
+      ))}
+      <li>
+        <button onClick={() => void user.createTodoList({ title: "New list" })}>
+          New list
+        </button>
+      </li>
+    </ul>
+  );
+};
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <RebootClientProvider url={import.meta.env.VITE_REBOOT_URL}>
+      <Root />
+    </RebootClientProvider>
+  </StrictMode>
+);
diff --git a/tests/reboot/react/test_long_running_fetches/test.py b/tests/reboot/react/test_long_running_fetches/test.py
index 81e0bc615..19c198cfa 100644
--- a/tests/reboot/react/test_long_running_fetches/test.py
+++ b/tests/reboot/react/test_long_running_fetches/test.py
@@ -64,8 +64,8 @@ def look_for_warning(
                         f":{parsed_uri.port}). You can "
                         "solve this by ensuring you use "
                         "HTTP/2 which requires TLS. See "
-                        "https://docs.reboot.dev/tools"
-                        "/cli/#bring-your-own-certificate"
+                        "https://docs.reboot.dev/rbt_cli"
+                        "#bring-your-own-certificate"
                         "-with-rbt-dev-run for details on "
                         "how to use TLS with 'rbt dev' "
                         "(which works similarly for "
@@ -87,8 +87,8 @@ def look_for_warning(
                         f":{parsed_uri.port}). You can "
                         "solve this by ensuring you use "
                         "HTTP/2 which requires TLS. See "
-                        "https://docs.reboot.dev/tools"
-                        "/cli/#bring-your-own-certificate"
+                        "https://docs.reboot.dev/rbt_cli"
+                        "#bring-your-own-certificate"
                         "-with-rbt-dev-run for details on "
                         "how to use TLS with 'rbt dev' "
                         "(which works similarly for "