[Improvement] Docs: symlink Stimulus controllers to gem source instead of copying

docs/app/javascript/controllers/ruby_ui/*_controller.js was a hand-maintained
copy of gem/lib/ruby_ui/<component>/*_controller.js. The two silently drifted:
the gem's accordion fix (0897b2a) never landed in the docs copy, breaking the
live accordion preview. Replace all 37 copies with relative symlinks into the
gem source, matching how docs already autoloads Phlex components straight
from gem/ (config/initializers/ruby_ui.rb) with no copy step.

- accordion_controller.js, avatar_controller.js, combobox_controller.js, and
  sheet_controller.js had genuinely stale docs content pre-migration (beyond
  just accordion) - the symlink now serves the gem's current, correct version.
- esbuild's default symlink handling resolves module imports relative to the
  symlink's real (gem/) path, which breaks node_modules resolution since gem/
  and docs/ are siblings with no shared ancestor node_modules. Build with
  --preserve-symlinks so imports resolve against the symlink location instead.
- Add `rake ruby_ui:sync_controller_symlinks` (docs/lib/tasks/ruby_ui.rake):
  scans gem/lib/ruby_ui for *_controller.js and creates/repairs the matching
  symlink. Idempotent. Replaces the old "copy the file by hand" step for new
  components; stimulus:manifest:update is still required separately to
  register a brand-new controller in the manifest.
- Update CLAUDE.md, docs/CLAUDE.md, gem/AGENTS.md, and the ruby-ui-stimulus
  skill to describe the symlink relationship and new workflow.

Supersedes still-open PR #490 for accordion_controller.js specifically: that
PR's docs-side fix is now moot since the file is a symlink to the (already
correct) gem source. Leaving #490's fate to a human reviewer.

Author: djalmaaraujo

.claude/skills/ruby-ui-stimulus/SKILL.md

@@ -41,6 +41,10 @@ Building or changing a Stimulus-backed component:
    - Importmap apps eager-load `controllers/` — no manifest edit needed.
    - esbuild/webpack apps regenerate the manifest with
      `rake stimulus:manifest:update` (`docs/app/javascript/controllers/index.js`).
+   - `docs/app/javascript/controllers/ruby_ui/<component>_controller.js` is a
+     symlink to the gem file above, not a copy. For a brand-new controller, run
+     `bin/rails ruby_ui:sync_controller_symlinks` in `docs/` first to create the
+     symlink, then `stimulus:manifest:update` to register it.
    - New JS packages go in `gem/package.json` **and** per-component in
      `gem/lib/generators/ruby_ui/dependencies.yml`.
 5. **Update docs & tests** in the same PR: `<component>_docs.rb` and

CLAUDE.md

@@ -20,6 +20,7 @@ Subproject-specific instructions live in `gem/AGENTS.md` and `docs/CLAUDE.md` (
 - Component docs view → `docs/app/views/docs/<component>.rb`. Update in same PR as the component.
 - Generator/installer logic → `gem/lib/generators/ruby_ui/`. Dependency map → `gem/lib/generators/ruby_ui/dependencies.yml`.
 - Site chrome, routes, marketing pages → `docs/app/`.
+- A component's Stimulus controller lives only in `gem/lib/ruby_ui/<component>/<component>_controller.js`. `docs/app/javascript/controllers/ruby_ui/<component>_controller.js` is a symlink to it, not a copy — editing the gem file is enough for existing components. A brand-new component's controller needs `docs`' `rake ruby_ui:sync_controller_symlinks` to create the symlink, plus `bin/rails stimulus:manifest:update` to register it.
 
 ## Common commands
 

docs/CLAUDE.md

@@ -19,3 +19,16 @@ bin/rails site_files:generate
 ```
 
 Before finishing, review the diff for `public/llms.txt`, `public/llms-full.txt`, and `public/sitemap.xml`. These generated files should be committed with the route/controller/view change so deployed apps expose the updated root files without a manual step.
+
+## Stimulus Controllers
+
+`app/javascript/controllers/ruby_ui/*_controller.js` are symlinks into `gem/lib/ruby_ui/<component>/`, not copies — there is no independent docs version to keep in sync.
+
+Adding a brand-new component's controller:
+
+```bash
+bin/rails ruby_ui:sync_controller_symlinks   # creates the missing symlink(s)
+bin/rails stimulus:manifest:update           # registers it in controllers/index.js
+```
+
+`sync_controller_symlinks` (in `lib/tasks/ruby_ui.rake`) is idempotent — safe to re-run any time. It only creates/repairs symlinks; it does not touch the manifest, so `stimulus:manifest:update` is still a separate required step for a controller the manifest hasn't seen yet.

docs/app/javascript/controllers/ruby_ui/accordion_controller.js

@@ -0,0 +1 @@
+../../../../../gem/lib/ruby_ui/accordion/accordion_controller.js

docs/app/javascript/controllers/ruby_ui/accordion_controller.js

@@ -0,0 +1 @@
+../../../../../gem/lib/ruby_ui/alert_dialog/alert_dialog_controller.js

docs/app/javascript/controllers/ruby_ui/alert_dialog_controller.js

@@ -0,0 +1 @@
+../../../../../gem/lib/ruby_ui/avatar/avatar_controller.js