docs: add remote-UI explainer for contributors

[mfal]

What

Adds a single conceptual explainer, docs/remote-ui.md, that makes the Flow remote-UI ("flr") system understandable to contributors (humans and agents) and spells out what remote-capability means when you implement or change a component. Existing AGENTS.md files now link to it instead of duplicating the concepts.

Why

Remote-UI is one of Flow's three core systems but the least discoverable — knowledge was scattered across terse package AGENTS.md files and procedural CONTRIBUTE.md steps, with no single explanation of how it works end to end or what it means for building components. That gap makes it easy to break the extension-facing contract, forget the generate/commit step, or compose components in a way that silently breaks remote rendering.

What the explainer covers

• Why remote-UI exists and the end-to-end architecture (Mermaid diagram + package-roles table)
• The mental model — render-and-mirror / events-back, the "everything rendered remote-side must be remote-capable" principle (with the user-land caveat), worked examples for List and Suspense, an ASCII boundary sketch
• The generation pipeline (@flr-generate → views + auto-generated/**)
• Implementing a component — the three participation modes (self remote-capable / universal / host-only, incl. the silent-break gotcha), how props cross the boundary (on* events, one-arg handlers, ReactNode→slots, no attributes, runtime serialization coercion), ref/controller/tunnel, controlled-input echo-suppression + allowlist, placement + propTypes registration, PropsContext asymmetry, and the Definition of Done
• Versioning & backwards compatibility — the two version mechanisms, the HostExports boundary, the deprecation delivery path
• Host-side special cases and where to go deeper

Notes

• Documentation only — no source files touched.
• Every file path and identifier cited was verified against the code; Prettier passes.
• AGENTS.md edits only add links (plus Prettier re-wrapping) — no content removed.

🤖 Generated with Claude Code

[github-actions]

Coverage Report for ./packages/components/

Status	Category	Percentage	Covered / Total
🔵	Lines	80.59%	324 / 402
🔵	Statements	80.53%	331 / 411
🔵	Functions	85.22%	75 / 88
🔵	Branches	67.26%	150 / 223

File Coverage

No changed files found.

Generated in workflow #5684 for commit 7613958 by the Vitest Coverage Report Action

[github-actions]

🚀 Preview Deployment

Preview environments are ready:

Type	URL
docs	pr-2665.docs.review.flow-components.de
storybook	pr-2665.storybook.review.flow-components.de

Images:

• docs: ghcr.io/mittwald/flow/docs:pr-2665
• storybook: ghcr.io/mittwald/flow/storybook:pr-2665