docs: add guidance for scaling state

[Alek99]

What changed

• add a new Scaling State guide with a decision framework for feature-owned State, cross-State access, inheritance, mixins, ComponentState, decentralized handlers, testing, and performance
• make the guide the entry point for the State Structure section and reconcile the existing code-structure, State overview, mixin, and ComponentState guidance
• route agent-readable Markdown, llms.txt, llms-full.txt, Skills, Agent Toolkit, and AGENTS.md guidance through the large-app reading path
• restore redirects for legacy /substates/* URLs and add regression coverage

Why

The existing docs explain each State primitive separately, but do not give humans or coding agents a normative way to choose and combine them in a scaled, multi-page app. This makes State ownership, coupling, and inheritance decisions under-specified.

Validation

• uv run --no-sync pytest tests -q — 406 passed, 1 skipped, 1 xfailed
• targeted Ruff check and format check
• Codespell across the modified docs
• git diff --check

uv run --no-sync reflex compile --dry initialized the docs app, but a full compile requires a Reflex Enterprise login in this environment.

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing docs/scaling-state (d8a78e6) with main (7e57be7)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[greptile-apps]

Greptile Summary

The PR adds a comprehensive Scaling State guide and incorporates it into the documentation paths used by developers and coding agents.

• Reconciles existing State, mixin, ComponentState, and project-structure guidance with the new scaling recommendations.
• Adds architecture links to generated Markdown assets, llms.txt, llms-full.txt, Skills, Agent Toolkit, and AGENTS.md guidance.
• Restores legacy substate redirects and adds focused route, sidebar, and generated-agent-file regression coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/state_structure/scaling_state.md	Adds the central decision guide for State ownership, composition, cross-State access, testing, and performance.
docs/app/agent_files/_plugin.py	Routes generated agent-readable documentation toward the new scaling guide and related architecture pages.
docs/app/reflex_docs/redirects.py	Centralizes documentation redirects and restores legacy substate mappings to existing State Structure routes.
docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py	Adds Scaling State to the State Structure sidebar while retaining the documented section ordering.
docs/app/tests/test_agent_files.py	Extends coverage for architecture links in generated Markdown, llms.txt, and llms-full.txt output.
docs/app/tests/test_routes.py	Adds regression assertions for the restored legacy substate redirects.
docs/app/tests/test_sidebar.py	Verifies the intended placement of Scaling State in the State Structure section.

_{Reviews (4): Last reviewed commit: "docs: make redirect test platform-safe" | Re-trigger Greptile}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[masenf]

this is the only one that i'm hesitant on because decentralized handlers are defined in a weird way and don't feel very reflexy to me, so idk if we should recommend them.

[adhami3310]

I agree, decentralized handlers if anything is an anti pattern that masks having too large of a state.