docs: corrections and pitfalls from AI builder field notes

[amsraman]

What

Five doc pages get corrections and pitfall callouts sourced from Reflex Build's curated knowledge base — rules our AI builder learned from real failures that turned out to be gaps (and in one case an error) in these pages. We're consolidating that knowledge base into the official docs so users and agents read the same source of truth (flexgen ENG-10044).

• library/forms/upload.md — bug fix: rx.get_upload_url was documented as returning str; it returns a frontend Var and is unusable in backend handlers/computed vars (backend alternative noted). Plus: upload id must be a string literal, file.name note, handlers must not be background=True, the upload trigger button must live outside the dropzone, a short "Uploading from a Form" subsection (on_submit never carries file data), and don't hardcode /_upload/ paths.
• enterprise/drag-and-drop.md — @rx.memo params are Vars (index / rx.foreach, no Python loops); on_drag_start doesn't exist; nested drop targets fire once per layer (dedupe) + root-level drop pattern; assign collected_params to a variable before reading fields, with a _collected_params=..._replace(_js_expr=...) example for multiple zones in one memo component; warning against adding a second DnD provider.
• state_structure/shared_state.md — sanitize tokens derived from query params (underscore restriction); _link_to pitfalls (must await, use the returned instance, only exists on rx.SharedState); computed vars depending only on shared vars belong on the shared state.
• utility_methods/lifespan_tasks.md — a "Lifespan Tasks vs Background Events" decision section.
• library/typography/markdown.md — literal $ pairs are parsed as LaTeX math (prices vanish, notably in streamed LLM output); escape before rx.markdown.

All additions follow each page's existing conventions (md alert callouts, demo blocks, doc voice). No behavioral claims were included that we couldn't verify against current reflex (e.g. we dropped a stale note about file.filename — it exists as an alias of .name).

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing docs/builder-field-notes-pitfalls (91fddab) with main (65a2889)²}

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. ↩

2. No successful run was found on main (127e4d8) during the generation of this report, so 65a2889 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 021e99e9f3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use the configured upload endpoint for backend URLs

When users follow this backend fallback in deployments with backend_path or a separately served API, building from self.router.headers.host omits the configured upload prefix and scheme that get_upload_url gets from getBackendURL(env.UPLOAD) and that the server mounts via config.prepend_backend_path(str(Endpoint.UPLOAD)). This can produce links that work locally but 404 in prefixed/split frontend-backend deployments; point backend-only examples at the configured upload endpoint (for example Endpoint.UPLOAD.get_url() plus the filename) instead of the Host header.

Useful? React with 👍 / 👎.

[amsraman]

Fixed in ac11db3 — the backend note now points at Endpoint.UPLOAD.get_url() joined with the filename instead of the Host header.

[greptile-apps]

Greptile Summary

This PR adds documentation corrections and pitfall callouts across five pages, sourced from real-world failures observed in Reflex Build's AI builder. The changes fix a stale return-type claim for rx.get_upload_url (it returns a frontend Var, not str) and add md alert warning blocks covering upload handler constraints, drag-and-drop event lifecycle, SharedState token sanitization and linking semantics, lifespan-vs-background-event guidance, and dollar-sign escaping in rx.markdown.

• upload.md: Corrects get_upload_url return type; adds pitfalls for background=True, button placement, form integration, and hardcoded /_upload/ paths. The backend URL hint references Endpoint.UPLOAD.get_url() from the internal reflex.constants module — a stability caveat and join example would improve it.
• drag-and-drop.md: Adds no-on_drag_start note, nested-drop deduplication guidance, collected_params variable assignment warning, dual-zone _replace/_js_expr example (already carries an internal-API caveat), and a second-provider warning.
• shared_state.md / lifespan_tasks.md / markdown.md: Token sanitization, _link_to pitfalls, lifespan-vs-background decision guide, and dollar-sign math escaping — all accurate and well-placed.

Confidence Score: 5/5

Safe to merge — all changes are documentation only with no runtime code touched.

All five files are Markdown documentation pages. The content additions are accurate, well-scoped, and consistent with the existing doc voice. The only finding is a missing stability caveat and join-syntax example for an internal API reference in upload.md, which does not affect any running code.

docs/library/forms/upload.md — the Endpoint.UPLOAD.get_url() hint could be clarified with a stability note and a concrete join example.

Important Files Changed

Filename	Overview
docs/library/forms/upload.md	Adds pitfall callouts for upload id type, get_upload_url return type (Var not str), background=True restriction, button placement, form usage, and path hardcoding. The backend URL hint references an internal API without a stability caveat or concrete join example.
docs/enterprise/drag-and-drop.md	Adds no-drag-start-event note, nested-drop deduplication guidance, collected_params variable assignment warning, dual-zone _replace/_js_expr example (with internal API caveat already added), and second-provider warning. All additions are accurate and well-placed.
docs/state_structure/shared_state.md	Adds token sanitization guidance inside the existing underscore restriction warning and a new pitfalls block covering await, returned instance, and get_state usage for _link_to; also adds a note about SharedState-only computed vars. All additions are accurate.
docs/utility_methods/lifespan_tasks.md	Adds a clear "Lifespan Tasks vs Background Events" decision section with examples, positioned before the existing Tasks section. Content is accurate and helpful.
docs/library/typography/markdown.md	Adds a warning about dollar signs being parsed as LaTeX math delimiters with the correct escape pattern. Small, accurate, and well-targeted at the LLM streaming use case.

_{Reviews (3): Last reviewed commit: "docs: ruff-format the drag-and-drop exam..." | Re-trigger Greptile}