Docs overhaul by rjhuijsman · Pull Request #154 · reboot-dev/reboot

rjhuijsman · 2026-09-04T13:56:12Z

Before this PR, the docs presented Reboot as a framework to build either an AI chat app, or a web app. It also had a "Quick"start that wasn't quick at all, barely mentioned auth, and the whole thing read like a different product than what we sell on the reboot.dev home page. It wasn't a good representation of Reboot at all!

This PR reorganizes the docs and (re)writes a lot of content to fix that.

The high-level changes:

One product, one argument. The opening pages carry the reboot.dev message and vocabulary, so arriving from the marketing page has a continuous story.
One app, several surfaces: one application can have all of a web frontend, MCP UIs, a React Native app, MCP tools, [...] - it's all just one application.
Users and auth front and center: our auth story has matured a lot, and you need to know about it to build a good app.
The agent path is the front door. One guide per agent (Claude/Codex); the hand-write-it Quickstart is gone (but the step-by-step guides remain for readers who want to see every file).
Python → Pydantic, TypeScript → Zod. Protobuf remains only where it is the actual encoding with no alternative API.

Key decisions I'd like feedback on:

React Native is documented, but marked alpha. The reboot.dev marketing page still says mobile is "Soon".
Protobuf is mostly removed from the docs, as it is now an implementation detail for ~all users.
rbt init is removed from the docs, because it still scaffolds a protobuf project. We can put it back when we update it to Pydantic.

aviator-app · 2026-09-04T13:56:15Z

Current Aviator status

Aviator will automatically update this comment as the status of the PR changes.
Comment /aviator refresh to force Aviator to re-examine your PR (or learn about other /aviator commands).

This pull request is currently open (not queued).

How to merge

To merge this PR, comment /aviator merge or add the mergequeue-ready label.

See the real-time status of this PR on the Aviator webapp.

Use the Aviator Chrome Extension to see the status of your PR within GitHub.

Before this change, the docs were organized around where an application runs: `full_stack_apps/`, `ai_chat_apps/`, and a catch-all `learn_more/`. That layout presented Reboot as a framework for AI chat apps with a web option on the side, and it kept the reference pages away from the guides that lead into them. Reboot is a general-purpose application framework, and its docs should be organized around what an application is: how its API is defined, implemented, and called, who its users are, and the surfaces it serves. This commit is the pure re-layout, kept free of prose changes so that it reviews as renames (`git diff -M`) and so that the rewrites in the following commits can be read against the moved text. Old URLs keep resolving through redirects, because generated servicer boilerplate, example READMEs, error messages, and reboot.dev link to them. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Before this change, three things a newcomer needs were missing or buried. There was no page explaining the mental model before the reference. Auth was a single page under "Learn more", even though every application starts from "who is this?" and `User` auto-construction is where an application begins. And the frontends were presented as two kinds of app, rather than as one backend with several front doors. These sections are the heart of the repositioning: a concepts page to read once, a users section that leads with sign-in and `User` auto-construction, and a surfaces section that presents web, React Native, and AI chat as peers. They cross-link heavily and every commit in this series builds, so they land together. The users pages are written around a todo-list example instead of the bank, so that `User` is unmistakably the person (their profile and what they own) with no second concept competing for that role, and so that the client side of sign-in reads as the two hooks it is. The example is real, tested code under `tests/reboot/documentation/`, so the snippets cannot drift from what runs. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Before this change, there were two Claude Code guides, two Codex guides, and two examples pages, one of each per kind of app. That duplicated the install and workflow steps, and it implied a choice the developer does not have to make up front: the agent skills build either kind of app, or both, from one description. One guide per agent keeps the docs' front door a single page, and one examples page lets the examples be grouped by what they demonstrate. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Before this change, the overview and the reboot.dev home page read like two different products. The home page leads with trusting the code your agent writes and a full-stack framework for the AI era; the overview opened on two kinds of app and a feature list, so a reader arriving from reboot.dev met a handoff rather than continuity. The overview now carries the home page's message and vocabulary, so the marketing site and the docs make one argument. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

With the users and surfaces sections in place, the reference pages that describe an API no longer need to explain sign-in, `User`, or MCP exposure themselves. They can say what is specific to defining, implementing, and calling an API and point at those sections for the rest, which keeps one explanation of each idea in one place. It also lets the advice on state IDs agree with "How Reboot works": prefer an explicit constructor, which lets Reboot generate the ID, for the types an application creates many of. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

… pages These pages were written when the hand-written guides were the front door and sign-in was an afterthought. Now that the agent guides come first and users are central, they should point newcomers at the agent path, lead towards sign-in as the next step, and say what a signed-in application needs in tests and in production. The `rbt` CLI page also gains the command table the docs never had, so the CLI has one place that lists what it can do. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

The Quickstart was the biggest page in the docs and sat in the Get started section, so the first thing a newcomer saw after the agent guides was a wall of twenty hand-written steps, when the whole point of the agent path is that an agent writes those files. The step-by-step Python, TypeScript, and React guides remain for readers who want to see every file. reboot.dev links to the Quickstart's URL, which now redirects to the Claude Code guide. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Before this change, protobuf was offered as a third way to define an API, which made the story "Pydantic, or Zod, or protobuf, depending" instead of "Python uses Pydantic, TypeScript uses Zod". Protobuf is an implementation detail of Reboot, not part of the developer's job, so the docs should not present it as a choice. The one place it stays is the standard library's value encoding (`reboot.protobuf`, `@bufbuild/protobuf`), which has no alternative API. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Before this change, the README introduced Reboot as a framework for AI chat apps that also builds web apps, named a `Session` type that no longer exists as the entry point, and linked to docs URLs that now only redirect. As the front page on GitHub it should make the same argument as reboot.dev and then send readers into the reorganized docs. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Every other example on the page links to its source, so a reader could open the code; `ai-chat-counter` had no link because it has no repository of its own. It lives in this repository under `reboot/examples/`, so link it there. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Three pages told readers to use TLS because of a browser connection limit, with three different numbers and no explanation of what was being limited, so a reader could neither judge whether the advice applied to them nor trust the numbers. The React client is the source of truth: the limit is on WebSockets, one per reactive reader over plain HTTP, and HTTP/2 over TLS removes it. All three pages now say that, with the client's numbers. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

The `ChatRoom` example in the Python guide and on the Pydantic page omitted `mcp=`, which is a required argument, so anyone typing the guide in would have hit a validation error on their first `rbt dev run`. The guide should also say why the argument is there, since it is the one decision the API forces per method. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

The client's connection-limit warning linked to the old CLI page, and the redirect drops the anchor, so the link landed at the top of the page instead of on the certificate instructions. The sibling WebSocket-limit warning told readers to "see the documentation" without saying where. A warning that names the fix should take the reader straight to it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

The warning logged under `rbt dev run` when a call reaches a type with no `authorizer()` linked to a docs section that no longer exists, so the old URL only redirected to the top of the authorization page. The warning is most people's first contact with authorization, so it should land on the paragraph that explains it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

The method headings on the OAuth token manager page read "Fetch" and "Store", capitalized like prose, while the methods are called `fetch` and `store`. A heading that carries the name as it is typed is what a reader searches for and what the surrounding pages link to. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

…rther Neither `UI` methods nor "Agents inside your app" is a frontend, yet both sat as siblings of the web, React Native, and AI chat pages. `UI` methods are a detail of building an AI chat app, and an agent running inside your app is a backend feature that builds on tasks and side effects. Filing them where they belong keeps the frontends section a list of frontends. No page moved; only the sidebar changed. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Votcp4rQnqt25q6XJGNavW

Copilot

🟡 Changes recommended

Several new examples contain incorrect OAuth guidance, unsafe retry semantics, or code that fails when copied.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Reorganizes Reboot’s documentation around a unified application model, emphasizing agent-driven onboarding, authentication, and multiple frontend surfaces.

Changes:

Reworks navigation, introductory content, examples, and legacy redirects.
Adds comprehensive OAuth, user, web, React Native, and AI chat guidance.
Adds tested todo examples and updates runtime documentation links.

File summaries

File	Description
`tests/reboot/react/test_long_running_fetches/test.py`	Updates CLI documentation URLs.
`tests/reboot/documentation/todos.py`	Defines the todo example API.
`tests/reboot/documentation/todos_main.tsx`	Adds a typed React example.
`tests/reboot/documentation/test_todos.py`	Tests todo behavior and authorization.
`tests/reboot/documentation/BUILD.bazel`	Builds and type-checks todo examples.
`tests/reboot/documentation/backend/src/servicers/todos.py`	Implements todo servicers.
`reboot/web/index.ts`	Updates warning documentation links.
`reboot/aio/auth/authorizers.py`	Updates authorization guidance link.
`documentation/sidebars.js`	Reorganizes documentation navigation.
`documentation/package.json`	Adds redirect support.
`documentation/package-lock.json`	Locks the redirect plugin.
`documentation/docusaurus.config.ts`	Adds legacy-route redirects.
`documentation/docs/users/oauth.mdx`	Documents OAuth configuration.
`documentation/docs/users/external_apis.mdx`	Documents delegated external API access.
`documentation/docs/users/claims.mdx`	Documents identity claims.
`documentation/docs/tools/cli.md`	Removes the old CLI page.
`documentation/docs/testing.md`	Updates links and adds user-auth testing.
`documentation/docs/tasks.mdx`	Updates task documentation links.
`documentation/docs/surfaces/web.mdx`	Adds web application guidance.
`documentation/docs/surfaces/ui_methods.mdx`	Reframes and updates UI methods.
`documentation/docs/surfaces/react_native.mdx`	Adds alpha React Native guidance.
`documentation/docs/surfaces/overview.mdx`	Introduces the multi-surface model.
`documentation/docs/surfaces/ai_chat.mdx`	Adds unified AI chat guidance.
`documentation/docs/side_effects.md`	Updates internal links.
`documentation/docs/secrets.mdx`	Updates the testing link.
`documentation/docs/rbt_cli.md`	Replaces and expands CLI documentation.
`documentation/docs/overview.mdx`	Rewrites the documentation landing page.
`documentation/docs/nonlocal.md`	Adds tunneled sign-in guidance.
`documentation/docs/library_services/sorted_map.mdx`	Generalizes serialization wording.
`documentation/docs/library_services/overview.md`	Updates side-effect links.
`documentation/docs/library_services/ordered_map.mdx`	Updates terminology and links.
`documentation/docs/library_services/oauth_token_manager.mdx`	Updates API headings and links.
`documentation/docs/library_services/mailgun.md`	Updates secrets and body documentation.
`documentation/docs/library_services/item.mdx`	Clarifies supported value formats.
`documentation/docs/learn_more/mcp_apps.mdx`	Removes superseded MCP documentation.
`documentation/docs/learn_more/define/protobuf.mdx`	Removes the protobuf guide.
`documentation/docs/implement/writers.mdx`	Updates task links.
`documentation/docs/implement/workflows.mdx`	Updates links and snippet paths.
`documentation/docs/implement/transactions.mdx`	Updates links and snippet paths.
`documentation/docs/implement/servicers.mdx`	Updates API-format and implementation guidance.
`documentation/docs/implement/readers.mdx`	Adds reader implementation guidance.
`documentation/docs/implement/application.mdx`	Adds authentication and MCP guidance.
`documentation/docs/idempotency.mdx`	Updates links and snippet paths.
`documentation/docs/get_started/typescript.mdx`	Revises TypeScript onboarding.
`documentation/docs/get_started/react.mdx`	Revises React onboarding.
`documentation/docs/get_started/python.mdx`	Revises Python onboarding.
`documentation/docs/get_started/examples.md`	Consolidates application examples.
`documentation/docs/full_stack_apps/get_started_codex.mdx`	Removes superseded Codex guide.
`documentation/docs/full_stack_apps/get_started_claude_code.mdx`	Removes superseded Claude guide.
`documentation/docs/full_stack_apps/examples.md`	Removes superseded examples page.
`documentation/docs/errors.mdx`	Removes protobuf examples and updates links.
`documentation/docs/develop_locally.md`	Modernizes local-development guidance.
`documentation/docs/deploy_operate/import_export.md`	Updates task links.
`documentation/docs/deploy_on_your_own.md`	Documents production environment variables.
`documentation/docs/deploy_on_reboot_cloud.md`	Adds production authentication guidance.
`documentation/docs/define/zod.mdx`	Updates definition links.
`documentation/docs/define/pydantic.mdx`	Expands Pydantic and `User` guidance.
`documentation/docs/define/overview.mdx`	Refocuses API definition guidance.
`documentation/docs/define/methods.mdx`	Clarifies method kinds and MCP exposure.
`documentation/docs/call/via_http.mdx`	Updates client links.
`documentation/docs/call/overview.mdx`	Revises construction guidance and links.
`documentation/docs/call/from_within_your_app.mdx`	Updates internal-call guidance.
`documentation/docs/call/from_outside_your_app.mdx`	Updates external-call links.
`documentation/docs/call/from_mcp_client.mdx`	Updates MCP and authentication links.
`documentation/docs/ai_chat_apps/what_is.mdx`	Removes superseded AI chat overview.
`documentation/docs/ai_chat_apps/get_started_codex.mdx`	Removes the old Codex chat guide.
`documentation/docs/ai_chat_apps/get_started_claude_code.mdx`	Removes the old Claude chat guide.
`documentation/docs/ai_chat_apps/examples.mdx`	Removes the old chat examples page.
`documentation/docs/agents.mdx`	Reframes durable in-application agents.

Review details

Files not reviewed (1)

documentation/package-lock.json: Generated file

Suppressed comments (2)

documentation/docs/users/external_apis.mdx:146

create_event is not inherently idempotent, so wrapping it in at_least_once can create duplicate calendar events when the workflow retries after the remote call succeeds but before its result is memoized. Use at_most_once, or pass a stable idempotency key to an API that supports it and explain that choice.
documentation/docs/implement/application.mdx:131
For an application with a User type, token_verifier= is not an alternative to oauth=: it authenticates calls but never triggers User auto-construction, and startup rejects that configuration. Say that external-token verification must be combined with oauth= here, matching the linked tokens page.

Files reviewed: 79/81 changed files
Comments generated: 3
Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+const { user, isLoading } = useUser();
+const { response } = user.useListTodoLists();


+4. Add the SPA's origin to `allowed_origins`, and its base URL's
+   `/__/oauth/callback` to your identity provider.


+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"],
+)
+
+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,
+    )


rjhuijsman force-pushed the rjh.docs-general-purpose branch 25 times, most recently from f151dea to d0e72b0 Compare September 4, 2026 22:05

rjhuijsman changed the title ~~Docs: reposition Reboot as a general-purpose framework~~ Docs overhaul Sep 4, 2026

rjhuijsman force-pushed the rjh.docs-general-purpose branch from d0e72b0 to 0f9b117 Compare September 4, 2026 22:11

rjhuijsman marked this pull request as ready for review September 4, 2026 22:31

rjhuijsman requested a balanced review from Copilot September 4, 2026 22:31

rjhuijsman requested review from benh, onelxj and rileysdev September 4, 2026 22:31

rjhuijsman self-assigned this Sep 4, 2026

rjhuijsman added mergequeue-ready mergequeue-rebase and removed mergequeue-ready mergequeue-rebase labels Sep 4, 2026

Copilot started reviewing on behalf of rjhuijsman September 4, 2026 22:31 View session

rjhuijsman and others added 16 commits September 4, 2026 22:36

reboot-dev-bot force-pushed the rjh.docs-general-purpose branch from 0f9b117 to df7a703 Compare September 4, 2026 22:36

Copilot AI reviewed Sep 4, 2026

View reviewed changes

Navigation Menu

Uh oh!

Docs overhaul - #154

Docs overhaul#154
rjhuijsman wants to merge 16 commits into
mainfrom
rjh.docs-general-purpose

rjhuijsman commented Sep 4, 2026 •

edited

Loading

Uh oh!

aviator-app Bot commented Sep 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		const { user, isLoading } = useUser();
		const { response } = user.useListTodoLists();

		4. Add the SPA's origin to `allowed_origins`, and its base URL's
		`/__/oauth/callback` to your identity provider.

Uh oh!

Conversation

rjhuijsman commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aviator-app Bot commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current Aviator status

How to merge

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Files not reviewed (1)

Suppressed comments (2)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rjhuijsman commented Sep 4, 2026 •

edited

Loading

aviator-app Bot commented Sep 4, 2026 •

edited

Loading