[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

.github/workflows/ci.yml

@@ -57,6 +57,8 @@ jobs:
           cache-dependency-path: docs/pnpm-lock.yaml
       - name: Install dependencies
         run: pnpm install
+      - name: Build assets
+        run: pnpm build && pnpm build:css
       - name: Lint
         run: bundle exec standardrb
       - name: Run tests

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/.npmrc

@@ -0,0 +1 @@
+node-linker=hoisted

docs/CLAUDE.md

@@ -19,3 +19,22 @@ 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.
+
+### Why `--preserve-symlinks` and `.npmrc` exist
+
+`pnpm build` passes `--preserve-symlinks` to esbuild. Without it, esbuild resolves a symlinked controller's imports relative to its *real* path under `gem/`, which has no reachable `node_modules` for `@hotwired/stimulus`, `motion`, `maska`, `chart.js`, and friends — every symlinked controller with an external import fails to resolve.
+
+That flag then collides with pnpm's default symlinked `node_modules`: package-internal requires (`@hotwired/turbo-rails` → `@hotwired/turbo`, `motion` → `framer-motion/dom`) stop resolving too, because esbuild no longer follows the symlink into `.pnpm/<pkg>/node_modules`. `.npmrc` sets `node-linker=hoisted` so `node_modules` is a flat tree of real directories — the only symlinks left are the intentional controller ones, and both halves resolve. Changing either the flag or `.npmrc` without the other breaks `pnpm build`.

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