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

.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 `rake 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/alert_dialog_controller.js

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

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

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