nitro_kit 2.0.0.alpha.2 → 2.0.0.alpha.4

data/app/javascript/controllers/nk/combobox_controller.js

@@ -50,6 +50,7 @@ export default class extends Controller {
   }
 
   connect() {
+    this.outsidePointerDown = this.outsidePointerDown.bind(this);
     this.activeOption = null;
     this.enhanced = true;
     this.nativeRequired = this.requiredValue;
@@ -64,6 +65,7 @@ export default class extends Controller {
 
   disconnect() {
     this.stopPositioning?.();
+    this.stopOutsideDismissal();
     this.enhanced = false;
     const control = this.element.querySelector(
       ':scope > [data-slot="combobox-control"]',
@@ -143,6 +145,17 @@ export default class extends Controller {
   open() {
     if (this.inputTarget.disabled) return;
 
+    // A committed selection is replaced, not appended to: opening selects the
+    // visible text so the first keystroke starts a fresh filter.
+    if (!this.openValue && this.inputTarget.value !== "") {
+      this.inputTarget.select();
+      this.inputTarget.addEventListener(
+        "mouseup",
+        (event) => event.preventDefault(),
+        { once: true },
+      );
+    }
+
     this.openValue = true;
   }
 
@@ -151,10 +164,30 @@ export default class extends Controller {
     this.setActive(null);
   }
 
-  closeFromOutside(event) {
+  // Capture-phase document pointerdown mirrors the Dropdown controller: iOS
+  // Safari does not reliably deliver window click events for outside taps.
+  outsidePointerDown(event) {
     if (!this.element.contains(event.target)) this.close();
   }
 
+  startOutsideDismissal() {
+    if (this.stopOutsideDismissalListener) return;
+
+    document.addEventListener("pointerdown", this.outsidePointerDown, true);
+    this.stopOutsideDismissalListener = () => {
+      document.removeEventListener(
+        "pointerdown",
+        this.outsidePointerDown,
+        true,
+      );
+      this.stopOutsideDismissalListener = null;
+    };
+  }
+
+  stopOutsideDismissal() {
+    this.stopOutsideDismissalListener?.();
+  }
+
   filter() {
     const query = this.inputTarget.value.trim().toLocaleLowerCase();
     let exactMatch = null;
@@ -268,9 +301,11 @@ export default class extends Controller {
 
     if (open) {
       this.startPositioning();
+      this.startOutsideDismissal();
     } else {
       this.stopPositioning?.();
       this.stopPositioning = null;
+      this.stopOutsideDismissal();
     }
   }
 
@@ -351,6 +386,21 @@ export default class extends Controller {
 
     this.statusTarget.textContent =
       count === 0 ? this.noResultsMessage : this.resultsMessage(count);
+    this.toggleEmptyState(count === 0);
+  }
+
+  toggleEmptyState(empty) {
+    if (empty && !this.emptyElement) {
+      const item = document.createElement("li");
+      item.setAttribute("role", "presentation");
+      item.setAttribute("data-slot", "combobox-empty");
+      item.textContent = this.noResultsMessage;
+      this.listboxTarget.append(item);
+      this.emptyElement = item;
+    } else if (!empty && this.emptyElement) {
+      this.emptyElement.remove();
+      this.emptyElement = null;
+    }
   }
 
   get visibleOptions() {

data/app/javascript/controllers/nk/command_palette_controller.js

@@ -22,13 +22,13 @@ export default class extends Controller {
     this.connected = true;
     this.restoreFocus = true;
     this.loadedQuery = this.inputTarget.value;
-    this.triggerTarget.removeAttribute("command");
     this.searchTarget.hidden = false;
     this.element.dataset.enhanced = "true";
   }
 
   disconnect() {
     this.connected = false;
+    clearTimeout(this.openTimer);
     clearTimeout(this.searchTimer);
     const trigger = this.element.querySelector(
       ':scope > [data-slot="command-palette-trigger"]',
@@ -51,21 +51,25 @@ export default class extends Controller {
       });
     if (empty) empty.hidden = true;
     if (status) status.textContent = "";
-    trigger?.setAttribute("command", "show-modal");
     if (search) search.hidden = true;
     delete this.element.dataset.enhanced;
   }
 
-  open(event) {
-    event?.preventDefault();
-    if (!this.canOpen) return;
+  openedByTrigger(event) {
+    if (!this.canOpen) {
+      event.preventDefault();
+      event.stopPropagation();
+      return;
+    }
 
-    this.returnFocus = document.activeElement;
+    this.returnFocus = event.currentTarget;
     this.restoreFocus = true;
-    this.reset();
-    this.panelTarget.showModal();
-    this.inputTarget.focus();
-    if (this.hasFormTarget) this.submitSearch();
+    clearTimeout(this.openTimer);
+    this.openTimer = setTimeout(() => this.#prepareOpenPanel(), 0);
+  }
+
+  guardOpen(event) {
+    if (event.command === "show-modal" && !this.canOpen) event.preventDefault();
   }
 
   shortcut(event) {
@@ -87,7 +91,9 @@ export default class extends Controller {
       if (!this.canOpen) return;
 
       event.preventDefault();
-      this.open();
+      this.returnFocus = document.activeElement;
+      this.panelTarget.showModal();
+      this.#prepareOpenPanel();
     }
   }
 
@@ -246,4 +252,12 @@ export default class extends Controller {
 
     return !activeModal || activeModal.contains(this.element);
   }
+
+  #prepareOpenPanel() {
+    if (!this.panelTarget.open) return;
+
+    this.reset();
+    this.inputTarget.focus();
+    if (this.hasFormTarget) this.submitSearch();
+  }
 }

data/app/javascript/controllers/nk/dialog_controller.js

@@ -4,6 +4,43 @@ export default class extends Controller {
   static targets = ["panel"];
   static values = { dismissible: Boolean };
 
+  disconnect() {
+    this.returnFocus = null;
+  }
+
+  invoke(event) {
+    const invoker = event.target.closest(
+      "[command], [data-nk--dialog-command]",
+    );
+    if (!invoker || !this.element.contains(invoker) || invoker.disabled) return;
+
+    const command =
+      invoker.getAttribute("command") ||
+      invoker.getAttribute("data-nk--dialog-command");
+    if (!["show-modal", "close"].includes(command)) return;
+
+    const panel = this.#commandPanel(invoker);
+    if (!panel) return;
+    if (command === "show-modal") this.returnFocus = invoker;
+    if (this.#nativeRelationshipRuns(invoker, panel, command)) return;
+
+    event.preventDefault();
+    if (command === "show-modal" && !panel.open) panel.showModal();
+    if (command === "close" && panel.open) panel.close();
+  }
+
+  closeForCache() {
+    this.returnFocus = null;
+    if (this.panelTarget.open) this.panelTarget.close();
+  }
+
+  restoreFocus() {
+    const returnFocus = this.returnFocus;
+
+    this.returnFocus = null;
+    if (returnFocus?.isConnected) returnFocus.focus();
+  }
+
   dismiss(event) {
     if (!this.dismissibleValue || event.target !== this.panelTarget) return;
 
@@ -20,4 +57,21 @@ export default class extends Controller {
   cancel(event) {
     if (!this.dismissibleValue) event.preventDefault();
   }
+
+  #commandPanel(invoker) {
+    const targetId = invoker.getAttribute("commandfor");
+    if (targetId) {
+      const target = document.getElementById(targetId);
+      if (target instanceof HTMLDialogElement && this.element.contains(target))
+        return target;
+    }
+
+    return invoker.hasAttribute("data-nk--dialog-command")
+      ? this.panelTarget
+      : null;
+  }
+
+  #nativeRelationshipRuns(invoker, panel, command) {
+    return invoker.commandForElement === panel && invoker.command === command;
+  }
 }

data/app/javascript/controllers/nk/dropdown_controller.js

@@ -7,8 +7,13 @@ import {
 export default class extends Controller {
   static targets = ["trigger", "content", "item"];
 
+  connect() {
+    this.outsidePointerDown = this.outsidePointerDown.bind(this);
+  }
+
   disconnect() {
     this.stopPositioning?.();
+    this.stopOutsidePointerFallback();
   }
 
   openFromKeyboard(event) {
@@ -36,10 +41,12 @@ export default class extends Controller {
   focusOpened(event) {
     if (event.newState === "open") {
       this.startPositioning();
+      this.startOutsidePointerFallback();
       this.focusInitialItem();
     } else {
       this.stopPositioning?.();
       this.stopPositioning = null;
+      this.stopOutsidePointerFallback();
       this.focusLast = false;
       this.restoreFocus();
     }
@@ -65,6 +72,37 @@ export default class extends Controller {
     this.stopPositioning = observeOverlayPosition(update);
   }
 
+  startOutsidePointerFallback() {
+    if (!this.supportsPopover || this.stopOutsidePointerFallbackListener)
+      return;
+
+    document.addEventListener("pointerdown", this.outsidePointerDown, true);
+    this.stopOutsidePointerFallbackListener = () => {
+      document.removeEventListener(
+        "pointerdown",
+        this.outsidePointerDown,
+        true,
+      );
+      this.stopOutsidePointerFallbackListener = null;
+    };
+  }
+
+  stopOutsidePointerFallback() {
+    this.stopOutsidePointerFallbackListener?.();
+  }
+
+  outsidePointerDown(event) {
+    if (!this.contentTarget.matches(":popover-open")) return;
+
+    const path = event.composedPath?.();
+    const insideMenu = path
+      ? path.includes(this.contentTarget) || path.includes(this.triggerTarget)
+      : this.contentTarget.contains(event.target) ||
+        this.triggerTarget.contains(event.target);
+
+    if (!insideMenu) this.hide();
+  }
+
   navigate(event) {
     switch (event.key) {
       case "Escape":
@@ -123,4 +161,11 @@ export default class extends Controller {
       (item) => !item.disabled && item.getAttribute("aria-disabled") !== "true",
     );
   }
+
+  get supportsPopover() {
+    return (
+      typeof this.contentTarget.showPopover === "function" &&
+      typeof this.contentTarget.hidePopover === "function"
+    );
+  }
 }

data/app/javascript/controllers/nk/dropzone_controller.js

@@ -230,8 +230,8 @@ export default class extends Controller {
     this.element.dataset.state = this.initialInputDisabled
       ? "disabled"
       : selectedCount > 0
-        ? "success"
-        : "idle";
+      ? "success"
+      : "idle";
   }
 
   replaceFiles(files) {

data/app/javascript/controllers/nk/progressive_image_controller.js

@@ -24,6 +24,10 @@ export default class extends Controller {
     if (this.hasFallbackTarget) this.fallbackTarget.hidden = true;
   }
 
+  prepareForCache() {
+    delete this.element.dataset.enhanced;
+  }
+
   imageTargetConnected(image) {
     if (this.connected) this.bindImage(image);
   }
@@ -47,11 +51,14 @@ export default class extends Controller {
     this.releaseImage();
     this.boundImage = image;
     this.revision = (this.revision || 0) + 1;
-    this.setState("loading");
     image.addEventListener("load", this.onLoad);
     image.addEventListener("error", this.onError);
 
-    if (image.complete) this.reflectComplete(image);
+    if (image.complete) {
+      this.reflectComplete(image);
+    } else {
+      this.setState("loading");
+    }
   }
 
   releaseImage() {
@@ -98,11 +105,8 @@ export default class extends Controller {
   }
 
   reflectComplete(image) {
-    if (image.naturalWidth > 0) {
-      this.loaded();
-    } else {
-      this.failed();
-    }
+    this.revision = (this.revision || 0) + 1;
+    this.setState(image.naturalWidth > 0 ? "loaded" : "error");
   }
 
   setState(state) {

data/app/javascript/controllers/nk/tabs_controller.js

@@ -42,10 +42,21 @@ export default class extends Controller {
     }
   }
 
+  reveal(event) {
+    const tab = this.tabTargets.find(
+      (candidate) => candidate.dataset.key === event.currentTarget.dataset.key,
+    );
+
+    if (tab && !tab.disabled) this.activeValue = tab.dataset.key;
+  }
+
   navigate(event) {
+    const rightToLeft = getComputedStyle(this.element).direction === "rtl";
     const directionKeys =
       this.orientationValue === "vertical"
         ? ["ArrowUp", "ArrowDown"]
+        : rightToLeft
+        ? ["ArrowRight", "ArrowLeft"]
         : ["ArrowLeft", "ArrowRight"];
 
     if (![...directionKeys, "Home", "End"].includes(event.key)) return;
@@ -140,9 +151,17 @@ export default class extends Controller {
 
     this.panelTargets.forEach((panel) => {
       const active = panel.dataset.key === value;
+      const tab = this.tabTargets.find(
+        (candidate) => candidate.dataset.key === panel.dataset.key,
+      );
 
-      panel.hidden = !active;
-      panel.setAttribute("aria-hidden", String(!active));
+      if (active) {
+        panel.removeAttribute("hidden");
+        panel.setAttribute("aria-hidden", "false");
+      } else {
+        panel.setAttribute("hidden", tab?.disabled ? "" : "until-found");
+        panel.removeAttribute("aria-hidden");
+      }
       panel.dataset.state = active ? "active" : "inactive";
       panel.tabIndex = active ? 0 : -1;
     });

data/app/javascript/controllers/nk/tooltip_controller.js

@@ -6,6 +6,8 @@ export default class extends Controller {
   }
 
   dismiss(event) {
+    if (!this.shown) return;
+
     event.preventDefault();
     this.element.dataset.dismissed = "";
   }
@@ -21,4 +23,11 @@ export default class extends Controller {
   reset() {
     delete this.element.dataset.dismissed;
   }
+
+  get shown() {
+    return (
+      !("dismissed" in this.element.dataset) &&
+      this.element.matches(":hover, :focus-within")
+    );
+  }
 }

data/config/locales/en.yml

@@ -12,7 +12,9 @@ en:
         dark: "Dark"
         system: "System"
     avatar_stack:
-      overflow: "%{count} more avatars"
+      overflow:
+        one: "%{count} more avatar"
+        other: "%{count} more avatars"
     combobox:
       invalid_selection: "Choose an option."
       no_results: "No options found."
@@ -37,6 +39,7 @@ en:
     dropzone:
       label: "Upload files"
       prompt: "Drop files here or choose them from your device."
+      compact_prompt: "Drop or choose files."
       preview_list: "Selected files"
       progress: "Upload progress"
       progress_for: "Upload progress for %{name}"

data/docs/agent_guide.md

@@ -1,8 +1,10 @@
-# Building applications with Nitro Kit
+# Nitro Kit application guide for coding agents
 
-This is the routing guide for coding agents working in a Rails application that uses Nitro Kit. It describes how to find the installed contract, select components, and apply the same Rails and Hotwire conventions across features.
+**Audience:** Coding agents changing a Rails application that uses Nitro Kit.
+Humans should start with the [README](../README.md) and
+[Rails integration guide](rails_integration.md).
 
-## Start from the installed version
+## Resolve the installed version
 
 From the application root, run:
 
@@ -10,130 +12,68 @@ From the application root, run:
 bundle show nitro_kit
 ```
 
-Read this guide from that directory, then consult only the reference needed for the task:
-
-| Task                                        | Read next                                 |
-| ------------------------------------------- | ----------------------------------------- |
-| Rails models, routes, CRUD, and tests       | `docs/rails_conventions.md`               |
-| Authentication, teams, shell, and settings  | `docs/patterns/application_foundation.md` |
-| Build a complete product resource           | `docs/patterns/crud_resource.md`          |
-| Choose or compose UI                        | `docs/component_contracts.md`             |
-| Rails assets, forms, and application shells | `docs/rails_integration.md`               |
-| Turbo, Frames, Streams, morphs, or Stimulus | `docs/hotwire.md`                         |
-| Theme tokens and application composition    | `docs/customization.md`                   |
-| Upgrade an existing Nitro Kit 1.x app        | `docs/migration_1_to_2.md`                |
-| Query, sort, filter, or paginate            | `docs/patterns/queryable_collection.md`   |
-| Create, update, and show validation         | `docs/patterns/resource_form.md`          |
-| Delete, revoke, archive, or confirm         | `docs/patterns/destructive_action.md`     |
-| Flash messages and notifications            | `docs/patterns/flash_and_toast.md`        |
-| Edit and cancel inside a page               | `docs/patterns/inline_edit.md`            |
-
-The installed component source is the final authority for constructor and compound-method details. This guide describes Nitro Kit 2.x. Do not use an API remembered from Nitro Kit 1.x or another installed version.
-
-## Select the highest-level matching component
-
-Prefer the component that owns the whole region, then compose smaller components inside it.
-
-| Product need                     | Begin with                                                |
-| -------------------------------- | --------------------------------------------------------- |
-| Application chrome               | `AppShell`, `AppNavigation`, `CommandPalette`             |
-| Authentication page              | `AuthShell`                                               |
-| Settings navigation              | `SettingsLayout`                                          |
-| Team or account administration   | `AppShell`, `Toolbar`, `Table`, `FormSection`             |
-| App page title and basic actions | `AppShell`, then `Toolbar`                                |
-| Content-led page introduction    | `PageHeader`                                              |
-| Data region                      | `DataSection`, then `Table` or `EmptyState`               |
-| Queryable tabular data           | `Table`, `Toolbar`, `PaginationBar`                       |
-| Model-backed form                | `FormSection`, Rails `form_with`, `NitroKit::FormBuilder` |
-| Destructive settings             | `DangerZone`, optionally `Dialog`                         |
-| Transient server feedback        | `Toast::FlashMessages`                                    |
-| Rendered Markdown or rich text   | `Container`, then `Typeset`                               |
-| General grouping                 | `Card`, `Flex`, `Grid`, `Container`                       |
-
-Application-specific product UI belongs under the application's namespace and composes Nitro components. Nitro owns component markup, styles, accessibility structure, and narrowly scoped progressive behavior. The application owns product policy, records, routes, authorization, queries, DOM IDs, and server responses.
-
-For admin CRUD, treat the starter and entitled flows as complete compositions:
-use toolbar Back links on child routes, keep deletion on edit, keep status in
-the details flow, implement full invitation and membership management, and use
-native links for settings destinations. Do not stop after rendering a screen
-that only looks structurally similar.
-
-## Preserve controls during migration
-
-Before changing a 1.x application, read `docs/migration_1_to_2.md`. Inventory
-user-facing flows and behavior before mapping helpers. When the Nitro Kit MCP
-catalog is available, search by product workflow rather than old component
-name, then prefer the highest-level matching composition before replacing
-atoms.
-
-After establishing that inventory, generate the host integration smoke tests
-from the currently bundled gem with `bin/rails generate
-nitro_kit:upgrade_smoke_tests`. The generator preserves existing files and
-skips missing Rails Minitest or system-test infrastructure with setup guidance.
-Run supported generated tests before and after the application conversion,
-while retaining application-specific acceptance coverage for every inventoried
-flow. Customize each generated `prepare_nitro_kit_upgrade_smoke_test` method
-with host sign-in and account-selection helpers when `ApplicationController`
-requires them; do not disable the host callbacks.
-
-In an existing application, replace a form control only when the installed
-Nitro Kit catalog provides a genuine semantic and behavioral equivalent.
-Preserve its parameter name, IDs, values, errors, accessibility, uploads, and
-browser behavior. If no equivalent exists, keep or re-express the control as
-application-owned Rails and semantic HTML, optionally inside a custom
-`form.field` composition. Never downgrade an editor, autocomplete, date range,
-upload, or other specialized input to the nearest generic Nitro control merely
-for visual consistency.
-
-Do not retain copied Nitro Kit 1.x source as the fallback. Remove the legacy
-component and preserve the unsupported behavior in clearly application-owned
-code. Report the missing equivalent as a Nitro Kit coverage gap.
-
-## Use one interaction grammar
-
-Choose the smallest primitive that completes the interaction:
-
-1. Ordinary Rails links and forms under Turbo Drive.
-2. A Turbo Frame for one independently navigable or replaceable region.
-3. A request-scoped Turbo Stream response when one action changes multiple regions.
-4. A broadcast only when other sessions must receive the change.
-5. Application Stimulus only for browser-only behavior the preceding layers cannot express.
-
-Successful non-GET HTML submissions redirect with `303 See Other`. Invalid form submissions render the same invalid model with `422 Unprocessable Entity`. GET parameters remain the source of truth for queryable collections. Frame identifiers come from `dom_id` or one named constant shared by rendering, responses, and tests.
-
-## Stay inside the public boundary
+Read this guide from that directory. The installed
+[component contracts](component_contracts.md) define the public API.
+
+| Task                                               | Read                                                         |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| Rails models, routes, CRUD, and tests              | [Rails conventions](rails_conventions.md)                    |
+| Authentication, teams, shell, and settings         | [Application foundation](patterns/application_foundation.md) |
+| Complete product CRUD                              | [CRUD resource](patterns/crud_resource.md)                   |
+| Components and composition                         | [Component contracts](component_contracts.md)                |
+| Installation, assets, forms, and Rails integration | [Rails integration](rails_integration.md)                    |
+| Turbo, Frames, Streams, morphs, or Stimulus        | [Hotwire](hotwire.md)                                        |
+| Browser compatibility or fallback behavior         | [Browser support](browser_support.md)                        |
+| Theme tokens and application CSS                   | [Customization](customization.md)                            |
+| Nitro Kit 1.x upgrade                              | [Migration guide](migration_1_to_2.md)                       |
+| Query, sort, filter, or paginate                   | [Queryable collection](patterns/queryable_collection.md)     |
+| Create, update, and validation                     | [Resource form](patterns/resource_form.md)                   |
+| Delete, revoke, archive, or confirm                | [Destructive action](patterns/destructive_action.md)         |
+| Flash messages and notifications                   | [Flash and toast](patterns/flash_and_toast.md)               |
+| Edit and cancel inside a page                      | [Inline edit](patterns/inline_edit.md)                       |
+
+Before changing a Nitro Kit 1.x application, read the migration guide. Do not
+infer 2.x APIs from memory or old application code.
+
+## Preserve the application's architecture
+
+For a greenfield application, run:
+
+```sh
+bin/rails generate phlex:install
+```
+
+Use Phlex for the application layout, route views, and reusable UI. In an established
+application, preserve its view architecture and introduce Phlex only at the
+requested boundary. Do not perform an application-wide migration unless it is
+explicitly authorized.
+
+## Stay within the public API
 
 - Include `NitroKit` once in the application's base Phlex component and use
-  capitalized Kit methods such as `Button(...)` and `Card(...)`.
-- Use the scoped `NitroKit::Button(...)` form when inclusion is not appropriate.
-- Use an explicit constructor such as `Button.new(...)` only when another API
-  needs a component object; Kit methods render immediately.
-- Select `NitroKit::FormBuilder` explicitly from Rails `form_with`.
-- Put a standalone form's visible fields, submit control, and related links
-  inside `form.group`; hidden fields may remain before the group.
-- Parents own rhythm. Wrap stacked fields in `FieldGroup` — as
-  `render NitroKit::FieldGroup.new { ... }`, or `form.group` inside a
-  `form_with` block. Two Fields, or a Field and its submit Button, rendered as
-  bare siblings of a `form` or a plain `div` have no gap between them at all.
-  Use `Flex` or `Grid` instead only when the arrangement is deliberately
-  inline or multi-column.
-- Use component options, compound declarations, layouts, and documented `--nk-*` theme properties.
-- Keep an HTML fallback for every Turbo form flow.
-- Test semantic output and stable owned attributes.
-
-Do not copy component source, add `nk_*` helpers, invent a general ERB bridge, mutate Nitro-owned Stimulus controllers, or pass `class:` and `style:`. The intentionally loud `desperately_need_a_class:` escape exists only for external integrations that require a class hook.
-
-## Application `AGENTS.md`
-
-Install the durable project instruction and local skills from the consuming
-application root:
+  Kit methods such as `Button(...)` and `Card(...)`.
+- Use `NitroKit::Button(...)` when inclusion is inappropriate and `.new` only
+  when another API requires a component object.
+- Select `NitroKit::FormBuilder` explicitly with Rails `form_with`.
+- Put stacked fields and actions in `form.group` or `FieldGroup`.
+- Use documented component options, compound methods, native attributes, and
+  public `--nk-*` tokens.
+- Keep product policy, records, routes, authorization, queries, DOM IDs, and
+  server responses in application code.
+- Do not copy Nitro source, add `nk_*` helpers, mutate Nitro controllers, or
+  pass `class:` or `style:`. Use `desperately_need_a_class:` only for a named
+  external integration that requires a class hook.
+
+Follow the canonical [browser support policy](browser_support.md) for
+JavaScript and fallback guarantees.
+
+## Install project-local guidance
+
+From the consuming application, run:
 
 ```sh
 bin/rails generate nitro_kit:install
 ```
 
-The installer preserves application-owned content around a bounded Nitro Kit 2
-block in `AGENTS.md` and adds project-local Rails, Hotwire, and UI skills for
-supported agents. The skills deliberately resolve the installed gem first, so
-upgrading the gem upgrades the instructions they use. Re-run the generator
-after an upgrade; it never copies component or controller source.
+The installer updates its managed `AGENTS.md` block and local Nitro Kit skills
+without copying component source. Re-run it after upgrading the gem.