Merge remote-tracking branch 'upstream/main' into try-orjson

Author: benedikt-bartscher

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,19 @@
+---
+name: Documentation
+about: Report a problem with the docs at reflex.dev/docs
+title: ""
+labels: documentation
+assignees: ""
+---
+
+**Page**
+Path:
+
+**What's wrong?**
+A clear description of the issue (typo, missing info, broken example, etc.).
+
+**Suggested fix (optional)**
+If you have a suggestion for how to improve the page, share it here.
+
+**Screenshots (optional)**
+If applicable, add screenshots to help explain.

AGENTS.md

@@ -46,6 +46,7 @@ docs/                   # documentation site (separate workspace member)
 - No block comments (`# --- Section ---`, `# ============`). Plain inline comments only.
 - Be cautious creating new public APIs — they must be documented and supported long-term.
 - Google-style docstrings on all functions: one-line summary, optional detail sentence(s), then Args/Returns (or Yields)/Raises.
+- Prefer imports at the top of the module in isort order. Only use inline imports when necessary to avoid circular dependencies.
 
 ## Testing
 

docs/advanced_onboarding/how-reflex-works.md

@@ -197,7 +197,7 @@ On the frontend, we maintain an event queue of all pending events.
 When an event is triggered, it is added to the queue. We have a `processing` flag to make sure only one event is processed at a time. This ensures that the state is always consistent and there aren't any race conditions with two event handlers modifying the state at the same time.
 
 ```md alert info
-# There are exceptions to this, such as [background events](/docs/events/background_events) which allow you to run events in the background without blocking the UI.
+# There are exceptions to this, such as [background events](/docs/events/background-events) which allow you to run events in the background without blocking the UI.
 ```
 
 Once the event is ready to be processed, it is sent to the backend through a WebSocket connection.
@@ -225,7 +225,7 @@ In our example, the `set_profile` event handler is run on the user's state. This
 
 ### State Updates
 
-Every time an event handler returns (or [yields](/docs/events/yield_events)), we save the state in the state manager and send the **state updates** to the frontend to update the UI.
+Every time an event handler returns (or [yields](/docs/events/yield-events)), we save the state in the state manager and send the **state updates** to the frontend to update the UI.
 
 To maintain performance as your state grows, internally Reflex keeps track of vars that were updated during the event handler (**dirty vars**). When the event handler is done processing, we find all the dirty vars and create a state update to send to the frontend.
 

docs/ai_builder/integrations/agents_md.md

@@ -0,0 +1,86 @@
+# AGENTS.md and CLAUDE.md
+
+`AGENTS.md` and `CLAUDE.md` are project-level instruction files that AI coding assistants read when they enter your repository. They give the assistant durable, repository-specific context so it follows Reflex conventions instead of generic defaults.
+
+- `AGENTS.md` is read by agents that follow the [AGENTS.md convention](https://agents.md), including Cursor, OpenCode, OpenAI Codex, and Pi.
+- `CLAUDE.md` is read by [Claude Code](https://code.claude.com/docs/en/memory). Claude Code does not read `AGENTS.md` directly — see [Sharing With Claude Code](#sharing-with-claude-code) below.
+
+A Reflex project should have at least one of these files at the project root, next to `rxconfig.py`.
+
+## Recommended Content
+
+The [reflex-dev/agent-skills](https://github.com/reflex-dev/agent-skills) repository ships an `AGENTS.md` template that points assistants at the [Reflex Agent Skills](/docs/ai/integrations/skills/) for environment setup, documentation lookup, and process management. Use it as the starting point, then add anything specific to your codebase.
+
+```md alert info
+# `AGENTS.md` references skills by name, so it works once the [Reflex Agent Skills](/docs/ai/integrations/skills/) are installed in the assistant.
+```
+
+## Installation
+
+Download the template into your project root, next to `rxconfig.py`:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reflex-dev/agent-skills/main/AGENTS.md -o AGENTS.md
+```
+
+Or copy it manually from a local clone of the [reflex-dev/agent-skills](https://github.com/reflex-dev/agent-skills) repository.
+
+## Sharing With Claude Code
+
+Claude Code reads `CLAUDE.md`, not `AGENTS.md`. To avoid duplicating content, create a `CLAUDE.md` that [imports](https://code.claude.com/docs/en/memory#import-additional-files) `AGENTS.md` using the `@` syntax:
+
+```md
+@AGENTS.md
+
+## Claude Code
+
+Add any Claude-specific instructions here.
+```
+
+Claude Code expands the `@AGENTS.md` import at session start, then appends anything you write below it. Both files stay in sync from a single source.
+
+After installation, your project root looks like:
+
+```text
+my_app/
+  AGENTS.md
+  CLAUDE.md
+  rxconfig.py
+  my_app/
+    my_app.py
+```
+
+## Project-Specific Additions
+
+The template covers Reflex-wide setup. Below it, add anything else the assistant should know about your project:
+
+- Internal conventions and code style.
+- Required lint, type-check, or test commands.
+- Folder layout and where new code should go.
+- Hosting or deployment notes.
+
+Keep entries short and imperative — assistants follow concise, direct instructions more reliably than long paragraphs.
+
+## Keeping Files Updated
+
+Reflex evolves quickly. If you used `curl` to download the template, re-run the same command to refresh it:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reflex-dev/agent-skills/main/AGENTS.md -o AGENTS.md
+```
+
+If you cloned the [reflex-dev/agent-skills](https://github.com/reflex-dev/agent-skills) repository, pull the latest changes and copy the file back into your project:
+
+```bash
+cd agent-skills
+git pull
+cp AGENTS.md /path/to/your/reflex-project/AGENTS.md
+```
+
+## Combining With Skills and MCP
+
+`AGENTS.md` and `CLAUDE.md` anchor the assistant in your project. Pair them with the other onboarding tools for deeper Reflex knowledge:
+
+- [Reflex Agent Skills](/docs/ai/integrations/skills/) provide reusable workflows that the file references by name.
+- [Reflex MCP](/docs/ai/integrations/mcp-overview/) provides structured documentation lookup at runtime.
+- The [llms.txt index](/llms.txt) gives a broad map of the documentation in one file.

docs/ai_builder/integrations/ai_onboarding.md

@@ -102,7 +102,7 @@ The index groups docs by section and links to agent-friendly Markdown assets.
 Use MCP when your editor or agent can call tools for structured documentation and component lookup:
 
 ```text
-https://mcp.reflex.dev/mcp
+https://build.reflex.dev/mcp
 ```
 
 See the [MCP overview](/docs/ai/integrations/mcp-overview/) and [MCP installation](/docs/ai/integrations/mcp-installation/) guides for details.

docs/ai_builder/integrations/mcp_installation.md

@@ -12,7 +12,7 @@ To use the Reflex MCP integration, you'll need to configure your AI assistant or
 
 ## Prerequisites
 
-- An MCP-compatible AI tool (Claude Desktop, Windsurf, Codex, etc.)
+- An MCP-compatible AI tool (Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf, etc.)
 - Internet connection to access the hosted MCP server
 - Valid Reflex account for OAuth 2.1 authentication
 
@@ -27,49 +27,105 @@ The Reflex MCP server uses OAuth 2.1 protocol for secure authentication. You'll
 Add the Reflex MCP server to Claude Code by running:
 
 ```bash
-claude mcp add --transport http reflex https://mcp.reflex.dev/mcp
+claude mcp add --transport http reflex https://build.reflex.dev/mcp
 ```
 
 Then authenticate by running the `/mcp` command inside Claude Code and following the login steps in your browser. Authentication tokens are stored securely and refreshed automatically. See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for more details.
 
 ### Claude Desktop
 
-Add the Reflex MCP server to your Claude Desktop configuration by editing your configuration file:
+Claude Desktop pulls remote MCP servers from your Claude account's connectors. Go to [claude.ai](https://claude.ai) → **Settings** → **Connectors** → **Add custom connector**, enter `https://build.reflex.dev/mcp` as the URL, and complete the OAuth login. The connector will then be available in Claude Desktop after you sign in. See the [custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for details and plan availability.
+
+### Codex
+
+Add the Reflex MCP server to Codex by running:
+
+```bash
+codex mcp add reflex --url https://build.reflex.dev/mcp
+```
+
+See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.
+
+### Cursor
+
+[Click here to install the Reflex MCP server in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=reflex&config=eyJ1cmwiOiJodHRwczovL2J1aWxkLnJlZmxleC5kZXYvbWNwIn0=), or edit (or create) `~/.cursor/mcp.json` for a global config, or `.cursor/mcp.json` in your project root for a project-specific config:
 
 ```json
 {
   "mcpServers": {
     "reflex": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://mcp.reflex.dev/mcp"]
+      "url": "https://build.reflex.dev/mcp"
     }
   }
 }
 ```
 
-### Windsurf/Cascade
+Open Cursor settings under **MCP & Integrations** to verify the server is connected and complete OAuth login. See the [Cursor MCP documentation](https://cursor.com/docs/context/mcp) for more details.
 
-Create a `.vscode/mcp.json` file in your project root:
+### Gemini CLI
+
+Add the Reflex MCP server to `~/.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "reflex": {
-      "serverType": "http",
-      "url": "https://mcp.reflex.dev/mcp"
+      "httpUrl": "https://build.reflex.dev/mcp"
     }
   }
 }
 ```
 
-### Codex
+See the [Gemini CLI MCP documentation](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) for more details.
+
+### GitHub Copilot
+
+Create a `.vscode/mcp.json` file in your project root (or open **MCP: Open User Configuration** from the VS Code command palette for a global config):
+
+```json
+{
+  "servers": {
+    "reflex": {
+      "type": "http",
+      "url": "https://build.reflex.dev/mcp"
+    }
+  }
+}
+```
 
-Add this configuration to your `~/.codex/config.toml` file:
+After saving, start the server from the inline action above the entry in `mcp.json`, then complete the OAuth login when prompted. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.
 
-```toml
-[mcp_servers.reflex]
-command = "npx"
-args = ["-y", "mcp-remote", "https://mcp.reflex.dev/mcp"]
+### OpenCode
+
+Add the Reflex MCP server to your `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "reflex": {
+      "type": "remote",
+      "url": "https://build.reflex.dev/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+See the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/) for more details.
+
+### Windsurf
+
+Edit (or create) `~/.codeium/windsurf/mcp_config.json` and add the Reflex server:
+
+```json
+{
+  "mcpServers": {
+    "reflex": {
+      "serverUrl": "https://build.reflex.dev/mcp"
+    }
+  }
+}
 ```
 
-Note: Codex requires MCP servers to communicate over stdio. The `mcp-remote` package bridges the connection to the HTTP-based Reflex MCP server.
+After saving, open Cascade and click the refresh icon in the MCP toolbar to load the new server. See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more details.

docs/ai_builder/integrations/mcp_overview.md

@@ -10,7 +10,7 @@ import reflex as rx
 
 The Reflex [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) integration provides AI assistants and coding tools with structured access to Reflex framework documentation and component information. This enables intelligent assistance while developing Reflex applications.
 
-The Reflex MCP server is deployed at `https://mcp.reflex.dev/mcp` and provides access to component documentation and Reflex documentation through standardized MCP tools.
+The Reflex MCP server is deployed at `https://build.reflex.dev/mcp` and provides access to component documentation and Reflex documentation through standardized MCP tools.
 
 ## Available Tools
 

docs/api-reference/event_triggers.md

@@ -73,7 +73,7 @@ def protected_page():
     return rx.text("Protected content")
 ```
 
-For more details on page load events, see the [page load events documentation](/docs/events/page_load_events).
+For more details on page load events, see the [page load events documentation](/docs/events/page-load-events).
 
 # Event Reference
 

docs/app/.github/workflows/integration_tests.yml

@@ -63,3 +63,6 @@ jobs:
 
       - name: Export the website
         run: reflex export
+
+      - name: Validate /docs links against generated sitemap
+        run: uv run python scripts/check_doc_links.py