Docs improvements by rileysdev · Pull Request #89 · reboot-dev/reboot

rileysdev · 2026-07-14T02:08:18Z

This is a large, though fairly straightforward, AI-assisted edit of our docs. This is edit 1 of 3, the highest priority items first. Though AI-assisted, I have read through every line of this change. That said, it still could use multiple pair of eyes, so I'm requesting multiple reviewers.

These changes include fixing factual inaccuracies, including more links, grammar and syntax improvements.

Reviewing indivual commits might be helpful for their bevity, though reading it top to bottom should be just as easy to understand.

Fixes #3363

Drop the "AI-provided configuration as props" claim: `show_clicker` has `request=None`, so no configuration reaches `App.tsx` (that feature is ai-chat-counter-dashboard's). Also link `workflow` to its docs, matching `what_is.mdx`. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

`User` methods get bare tool names, so it's `create_counter`, not `session_create_counter`; and the clicker tool is listed by its full name, `counter_show_clicker`. Also "we define" -> "you define" per the style guide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The settings.json snippet enables the plugin (`enabledPlugins`), not "the skill", which isn't introduced until later. Also restore the "UI methods use `UI()`..." sentence from the twin Codex page, so UI methods are introduced before "Next steps" links to their reference. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

aviator-app · 2026-07-14T02:08:20Z

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.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The guide teaches the bare minimum to get started; example prompts are generated by the Reboot plugin's skill, not hand-written. The main.py snippet is now hand-written (not mirrored from the ai-chat-counter example, which keeps its prompts). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

aviator-app · 2026-07-14T06:27:10Z

This pull request can't be queued because it's currently a draft.

The guide's web-app main.tsx snippet is now hand-written (not mirrored from the ai-chat-counter example, which keeps its stylesheet) so readers don't have to create a styles.css. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR is a broad documentation pass across the Reboot docs set, focused on correcting inaccuracies, improving clarity/grammar, and adding/updating links and examples (including MCP/UI and OAuth token-storage behaviors).

Changes:

Clarifies and refines conceptual docs across API definition, calling patterns, workflows/idempotency, auth, and MCP/UI integration.
Updates/expands several library-service docs (Queue, OrderedMap/SortedMap, PubSub, OAuthTokenManager, Mailgun, Ciphertext) with clearer wording and more precise guidance.
Fixes multiple broken/unclear references, anchors, and example snippets throughout the docs set.

Reviewed changes

Copilot reviewed 50 out of 50 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
reboot/examples/bank-pydantic/api/bank/v1/account.py	Reorders the `open` factory method definition for clearer “constructor” documentation extraction.
rbt/std/oauth/v1/oauth.proto	Clarifies `Store` semantics for OAuth token storage (wholesale replacement; caller must merge refresh token if needed).
documentation/docs/upgrade.md	Tightens upgrade guidance to specify “newer than pinned version, up to target.”
documentation/docs/tools/cli.md	Removes resolved TODO reference.
documentation/docs/library_services/sorted_map.mdx	Corrects reverse-range validity explanation (`end_key` relationship) and improves phrasing.
documentation/docs/library_services/queue.mdx	Refines Queue intro, wording, and examples around enqueue/dequeue usage.
documentation/docs/library_services/pubsub.mdx	Clarifies required libraries/servicers and improves wording/grammar.
documentation/docs/library_services/overview.md	Fixes grammar (“An older…”) and clarifies library-service inclusion at `Application` startup.
documentation/docs/library_services/ordered_map.mdx	Improves grammar/clarity, adjusts examples, and fixes an internal anchor reference.
documentation/docs/library_services/oauth_token_manager.mdx	Clarifies “store” semantics and refresh-token handling guidance.
documentation/docs/library_services/mailgun.md	Adds integration setup/auth details and clarifies `task_id` meaning.
documentation/docs/library_services/ciphertext.mdx	Fixes grammar and clarifies failure/rotation wording.
documentation/docs/learn_more/testing.md	Improves secrets/testing guidance, Node test-runner advice, and Vitest reporter explanation.
documentation/docs/learn_more/tasks.mdx	Fixes/updates link and clarifies watch behavior reference.
documentation/docs/learn_more/side_effects.md	Improves terminology consistency and fixes footnote/list formatting.
documentation/docs/learn_more/secrets.mdx	Adds Reboot Cloud auth context and improves cross-linking to testing harness docs.
documentation/docs/learn_more/mcp_apps.mdx	Adds links and clarifies MCP behavior around `UI` and `User` state.
documentation/docs/learn_more/implement/writers.mdx	Clarifies writer-call restrictions and aligns example naming/casing.
documentation/docs/learn_more/implement/workflows.mdx	Adds detail on snapshot/read idempotency and clarifies inline-writer semantics and TS schema requirements.
documentation/docs/learn_more/implement/ui_methods.mdx	Expands UI-method explanation and updates hook usage examples for MCP-aware ID resolution.
documentation/docs/learn_more/implement/transactions.mdx	Fixes TypeScript transaction servicer example to use `Bank` consistently.
documentation/docs/learn_more/implement/servicers.mdx	Updates wording to include Pydantic and improves clarity around servicer mapping and instance creation.
documentation/docs/learn_more/implement/readers.mdx	Clarifies reader semantics as “read-only access.”
documentation/docs/learn_more/identity_and_external_apis.mdx	Adds MCP cross-link and clarifies provider selection requirements/behavior.
documentation/docs/learn_more/idempotency.mdx	Adds cross-links and clarifies Python vs TypeScript idempotency key APIs.
documentation/docs/learn_more/errors.mdx	Expands error-definition guidance across Pydantic/Zod/Proto with clearer examples.
documentation/docs/learn_more/define/zod.mdx	Adds Zod intro and emphasizes field tags for backwards compatibility.
documentation/docs/learn_more/define/pydantic.mdx	Clarifies how `mcp=Tool()` affects AI tool exposure.
documentation/docs/learn_more/define/protobuf.mdx	Clarifies required imports and service-naming convention (`*Methods`).
documentation/docs/learn_more/define/overview.mdx	Clarifies terminology and broadens codegen note to include Pydantic.
documentation/docs/learn_more/define/methods.mdx	Fixes grammar and clarifies MCP exposure requirement for Pydantic-defined APIs.
documentation/docs/learn_more/call/via_http.mdx	Improves wording and adds link to `ExternalContext` docs.
documentation/docs/learn_more/call/overview.mdx	Clarifies “state ID” terminology and updates constructor/factory wording for Pydantic/Zod.
documentation/docs/learn_more/call/from_within_your_app.mdx	Clarifies workflow exception re: state snapshots and updates context capability table.
documentation/docs/learn_more/call/from_react.mdx	Expands hook usage guidance for MCP context and fixes small grammar issues.
documentation/docs/learn_more/call/from_outside_your_app.mdx	Improves definition of “external” calls and clarifies reactive readers explanation.
documentation/docs/learn_more/call/from_mcp_client.mdx	Improves cross-linking (UI methods, ngrok, auth provider docs) and wording.
documentation/docs/learn_more/auth.mdx	Fixes typos/grammar and normalizes terminology (“third-party”).
documentation/docs/learn_more/applications.mdx	Clarifies initialize auth token behavior and AI chat app auto-registration wording/links.
documentation/docs/learn_more/agents.mdx	Refines agent durability/idempotency explanations and updates terminology/wording.
documentation/docs/full_stack_apps/typescript.mdx	Fixes wording and renames servicer step to `ChatRoomServicer` for consistency.
documentation/docs/full_stack_apps/react.mdx	Fixes typos, corrects TypeScript link, and updates Vite default URL guidance.
documentation/docs/full_stack_apps/python.mdx	Clarifies API-definition language and improves `.rbtrc` and persistence explanations.
documentation/docs/full_stack_apps/examples.md	Fixes typos and clarifies example descriptions/names and cross-links.
documentation/docs/develop_locally.md	Replaces/condenses CLI install guidance and clarifies `--` passthrough semantics.
documentation/docs/deploy_on_your_own.md	Adds `rbt serve run` invocation and flag reference section.
documentation/docs/ai_chat_apps/what_is.mdx	Fixes grammar and clarifies how tool-exposed methods relate to state instances/IDs.
documentation/docs/ai_chat_apps/get_started.mdx	Updates quickstart steps/snippets and clarifies hook/tool naming and required files.
documentation/docs/ai_chat_apps/get_started_claude_code.mdx	Clarifies plugin enablement wording and adds UI-method note.
documentation/docs/ai_chat_apps/examples.mdx	Improves cross-linking and clarifies example feature descriptions.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

 you use it. [`Item`](/library_services/item)s can be [`Enqueue`](#enqueue)d as a
-single `Value`, `bytes`, or `Any` object or can be [`Enqueued`](#bulk-enqueue)ed
+single `Value`, `bytes`, or `Any` object or can be [`Enqueue`](#bulk-enqueue)d
 in bulk as a list of `Item`s. They can then be [`Dequeue`](#dequeue)d singularly
-in [bulk](#bulk-dequeue) as well. In practice, you will want to use just one of
+or in [bulk](#bulk-dequeue) as well. In practice, you will want to use just one of


+import {
+  type DashboardConfig,
+  type UseCounterApi,
+  useCounter,
+} from "@api/ai_chat_counter/v1/counter_rbt_react";


+import {
+  type UseCounterApi,
+  useCounter,
+} from "@api/ai_chat_counter/v1/counter_rbt_react";


+import {
+  type UseCounterApi,
+  useCounter,
+} from "@api/ai_chat_counter/v1/counter_rbt_react";


+import {
+  type DashboardConfig,
+  useCounter,
+} from "@api/ai_chat_counter/v1/counter_rbt_react";


onelxj

One request, your PR description refers to a ticket from our private repo. Let's close that ticket there, reopen it in public repo and then reference to it, thanks!

onelxj · 2026-07-14T11:11:23Z

 touch backend/src/main.py
 ```

-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../../../reboot/examples/ai-chat-counter/backend/src/main.py&syntax=python) -->


General question:
Why do we remove autodocs?
That's likely that if we change the code in the future we will forget to update the docs.

onelxj · 2026-07-14T11:17:50Z

   `http://localhost:9991/mcp`; otherwise use your Reboot Cloud
   URL (`https://your-app.prod1.rbt.cloud:9991/mcp`) or your
-   `ngrok` tunnel URL with `/mcp` appended.
+   [`ngrok`](/learn_more/nonlocal#ngrok) tunnel URL with `/mcp`


I thought that agent will run cloudflared in the background as a tunnel, shall we highlight that?

onelxj · 2026-07-14T11:19:11Z


 ```tsx
-import { useCounter } from "@api/ai_chat_counter/v1/counter_rbt_react";
+import {


Is there a chance we can make this be autodocs?

onelxj · 2026-07-14T11:22:18Z

 or _explicitly_, depending on whether or not you have explicitly
-designated certain methods as _constructors_ in your `.proto`, or a
-_factory_, in your Zod schema.
+designated certain methods as _constructors_ in your `.proto`, or as


Shall we remove the references to proto and Zod for now, since we are pushing for Pydantic/Python?

onelxj · 2026-07-14T11:23:52Z


-`rbt dev run` will automatically generate code from your Zod schemas
-or `.proto` files and reload your application when your API changes.
+`rbt dev run` will automatically generate code from your Pydantic


How about from your API .... and reload your application when it changes?

onelxj · 2026-07-14T11:30:32Z


 <Tabs groupId="language">
  <TabItem value="python" label="Python" default>
 ```py


Can we make this be autodocs?

onelxj · 2026-07-14T11:32:58Z


+Like calls, reads follow the workflow's
+[idempotency rules](#retries-and-idempotency): by default `read()` behaves as
+though you had used `.per_workflow()` (Python) / `.perWorkflow()`


Same question about Python vs Typescript docs.

onelxj · 2026-07-14T11:33:50Z


 If you want your inline writer to execute _every time_, use
-`.always()`, e.g., in TypeScript `this.state.always().write(context, ...)`.
+`.always()`, e.g., in TypeScript


This one should be Python based definitely.

onelxj · 2026-07-14T11:36:10Z

  retry policy).
- **Reboot's `at_least_once`** retries the wrapped block until it
-  succeeds.
+- **Reboot's `at_least_once`** doesn't itself retry, but a block


That is still slightly confusing, shall we explicitly call out that the Workflow body is a thing which is auto-retried and at_most/least_once are memoization guards that might skip steps or fail forever?

onelxj · 2026-07-14T11:37:06Z

+withdrawal. The error is itself defined as a type in your API and listed in the
+method's `errors`:

+<Tabs groupId="language">


Any change for autodocs here?

rileysdev and others added 11 commits July 14, 2026 02:07

Simple, low-stakes docs fixes

7ca7165

Fixes #3363

87e83e4

Docs: editorial and correctness cleanups

d3c8ebc

Drop nonexistent end_key from OrderedMap range examples

0a599b5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Document Mailgun bearer-token auth requirement

02fa639

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix stale useCounter() return shape in UI methods docs

fab7d84

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Document that rbt is installed with the Reboot library

54b480c

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Document the rbt serve run command and its flags

1644b92

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

rileysdev force-pushed the riley/docs-updates branch 2 times, most recently from 720b11b to a5e3a3a Compare July 14, 2026 06:25

rileysdev and others added 11 commits July 14, 2026 06:26

Fix Transfer TS examples to use the Bank servicer

a37015f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix Pydantic factory snippet line range in call overview

d1b8d07

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix no-args useCounter hook shape in from_react docs

3ae7d84

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix stale carry-forward comment on StoreRequest.tokens

d7d7718

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Document declaring errors in Pydantic and Zod APIs

4b05553

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Include dist config in get_started .rbtrc snippet

0e9571a

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fixup! Simple, low-stakes docs fixes

28012d5

fixup! Fix Pydantic factory snippet line range in call overview

ef4e709

Explain when workflow reads fetch a fresh snapshot

961c299

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fixup! Document that rbt is installed with the Reboot library

6ba0942

rileysdev added the mergequeue-ready label Jul 14, 2026

rileysdev self-assigned this Jul 14, 2026

aviator-app Bot removed the mergequeue-ready label Jul 14, 2026

rileysdev marked this pull request as ready for review July 14, 2026 06:27

rileysdev requested review from benh, Copilot, onelxj and rjhuijsman July 14, 2026 06:27

Copilot started reviewing on behalf of rileysdev July 14, 2026 06:27 View session

Keep styles.css out of the get-started guide

2bc6f56

The guide's web-app main.tsx snippet is now hand-written (not mirrored from the ai-chat-counter example, which keeps its stylesheet) so readers don't have to create a styles.css. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

rileysdev force-pushed the riley/docs-updates branch from a5e3a3a to 2bc6f56 Compare July 14, 2026 06:29

Copilot AI reviewed Jul 14, 2026

View reviewed changes

onelxj reviewed Jul 14, 2026

View reviewed changes

Uh oh!

Conversation

rileysdev commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aviator-app Bot commented Jul 14, 2026

Current Aviator status

How to merge

Uh oh!

aviator-app Bot commented Jul 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

onelxj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rileysdev commented Jul 14, 2026 •

edited

Loading