Docs: Legacy Migration Guidance

Summary

The migration docs should add a short, explicit section for legacy react-rails + Webpacker apps.

The current example-migrations work is useful, but the real friction discovered in indentlabs/notebook is not obvious from the existing migration guides: the package can work on an older Webpacker stack, but only with compatibility shims that many users will not anticipate.

What The Docs Should Clarify

1. The preferred path for Webpacker-era apps is usually "migrate to Shakapacker first" if the goal is a low-friction React on Rails adoption.
2. If users intentionally stay on Webpacker / Webpack 4 for a first incremental slice, they may need package-specific compatibility config.
3. SPA-root Vite Rails apps are a different category from Rails-owned island mounts and should be described as architecture case studies rather than quick first migrations.
4. Public migration examples should call out whether the evidence is performance-first or maintainability-first.

Why This Matters

The wrong docs framing creates two bad outcomes:

• teams think React on Rails is broken when the actual issue is legacy bundler compatibility
• teams pick a poor first target, like a client-routed SPA shell, and conclude the migration path is heavier than it really is

Suggested Placement

• react-rails migration guide
• example migrations page
• troubleshooting or compatibility appendix

Related

• Docs PR: docs: add example migrations guide #3126
• Meta issue: Track example migrations from existing Rails + React apps #3125
• Proof artifacts issue: Track missing proof artifacts for public migration examples #3127