nitro_kit 0.8.0 → 2.0.0.alpha.1

data/docs/implementation_plan.md

@@ -0,0 +1,279 @@
+# Nitro Kit 2.0 implementation record
+
+This document records the staged delivery program used for the agent-native pivot. `tk` is the source of truth for live status and dependency order; ticket IDs below connect durable design intent to executable work. Candidate lists in early stages are historical investigation prompts, not current public API. The settled contract lives in [`agent_native_spec.md`](agent_native_spec.md) and [`component_contracts.md`](component_contracts.md).
+
+Nitro Kit 2.0 is allowed to break 1.x completely. Each stage should leave one simpler system behind rather than maintaining parallel APIs.
+
+The original implementation program reached release-quality consolidation. Component migration, evidence-gathering flows, accepted layout/block extraction, the expanded gallery, 1.x removal, documentation, packaging, and browser verification are retained here as history; later contract revisions such as responsive Flex/Grid remain tracked in `tk` and the canonical contract documents.
+
+## Definition of done
+
+The 2.0 pivot is complete when:
+
+- Every component is constructed directly from Phlex with explicit Ruby options.
+- Nitro Kit owns the Ruby, markup contract, behavior, CSS, examples, and documentation.
+- No Nitro-authored component, layout, block, flow, or gallery subject emits `class`, `style`, or an escape marker.
+- Applications can theme the system through documented `--nk-*` variables and compose or subclass components.
+- Rails forms, routes, assets, Turbo Frames, and Turbo Streams remain first-class.
+- The gem does not expose `nk_*` view helpers, copied-component generators, a Tailwind runtime, or a template-buffer bridge.
+- The complete catalog renders through explicit Rails routes in light/dark and narrow/wide states.
+- Keyboard behavior and Turbo lifecycle behavior pass browser tests.
+- The full Ruby, CSS, JavaScript formatting, package, and browser checks pass from a clean checkout.
+
+## Delivery rules
+
+Every migration ticket follows the same sequence:
+
+1. Define the smallest explicit Ruby API and closed vocabularies.
+2. Render native, self-describing HTML with `data-nk` and qualified `data-slot` identities.
+3. Preserve Rails and accessibility semantics before visual styling.
+4. Add static zero-specificity CSS driven by public theme tokens and private mechanics variables.
+5. Add focused render, invalid-option, reserved-attribute, and integration tests.
+6. Add representative and exhaustive gallery examples without classes or escape hatches.
+7. Verify the family independently before allowing dependent flows to use it.
+
+No compatibility layer should survive merely to keep a legacy example green. Replace the example and delete the obsolete API.
+
+## Stage 0 — ownership and execution scaffold
+
+Tickets: `nk-rzxf`, `nk-g3qu`
+
+- Work on the dedicated `2.0-agent-native` branch.
+- Keep the agent-native specification, component contracts, repository guidance, and this plan tracked with the gem.
+- Track the entire program in the workspace-level `.tickets` database.
+- Record implementation decisions and verification counts on each ticket before closing it.
+
+Gate: an agent can explain who owns Ruby, markup, CSS, behavior, theming, composition, and the class escape hatch by reading the tracked docs.
+
+## Stage 1 — kernel and distribution foundation
+
+Tickets: `nk-6q5i`, `nk-fooc`, `nk-rx0j`
+
+- Replace permissive attributes with explicit component options plus `html:`, `aria:`, and `data:` boundaries.
+- Centralize identity, slot attachment, reserved attributes, validation, additive Stimulus data, and `desperately_need_a_class:`.
+- Build deterministic layered CSS from split plain-CSS sources.
+- Ship the built stylesheet, optional Tailwind adapter, importmap pins, and controllers from the gem without vendored third-party JavaScript.
+- Prove the engine still boots when importmap-rails is absent.
+
+Gate: a minimal Rails app can render and style a Nitro component without copying sources or configuring Tailwind or JavaScript pins.
+
+## Stage 2 — representative vertical slice
+
+Ticket: `nk-g3x1`
+
+Migrate Button/Icon, Card, Input/Field/FormBuilder, Table, and Dialog all the way through Ruby, HTML, CSS, behavior, Rails integration, tests, and gallery routes.
+
+Use this slice to settle:
+
+- Direct compound-component methods and nested slot ownership.
+- Native attribute boundaries and error messages.
+- Intrinsic versus stretch sizing.
+- Rails form names, IDs, values, errors, multipart behavior, and checkbox semantics.
+- Native dialog behavior, stable ARIA relationships, and Stimulus cleanup.
+- The explicit gallery catalog and route contract.
+
+Gate: the slice is classless, invalid options fail immediately, focused tests pass, and its examples render through real Rails routes with Nitro CSS alone.
+
+## Stage 3 — complete atom migration
+
+Tickets: `nk-t17c`, `nk-b18t`, `nk-7lkw`, `nk-4r36`, `nk-i4xu`, `nk-19gd`
+
+### Display
+
+Migrate Alert, Avatar, AvatarStack, Badge, and Icon. Cover semantic intents, long content, image/fallback behavior, overflow, sizes, labeled/decorative icons, and nested combinations.
+
+### Actions and navigation
+
+Migrate ButtonGroup and Pagination. Preserve native links/buttons, current-page semantics, disabled previous/next controls, ellipses, compact ranges, and stable labels.
+
+### Forms
+
+Migrate Label, Textarea, Select, Checkbox, CheckboxGroup, RadioButton, RadioButtonGroup, Switch, FieldGroup, Fieldset, and all FormBuilder methods. Cover:
+
+- Bound and unbound forms.
+- Required, disabled, readonly, checked, indeterminate, invalid, prompt, and empty states.
+- Array and nested parameter names.
+- Active Model values and errors.
+- Multipart uploads and native file-input constraints.
+- Accessible descriptions, legends, labels, and error relationships.
+
+### Structured content
+
+Migrate Accordion and Tabs alongside the Card and Table slice. Require deterministic IDs and keys, direct compound APIs, semantic table structure, and keyboard-visible state.
+
+### Interaction
+
+Migrate Dropdown, Tooltip, Combobox, and Toast alongside Dialog. Require closed placement/state APIs, visible ARIA/data state, keyboard behavior, native controls where possible, and complete disconnect cleanup.
+
+Gate: every shipped atom has a classless direct-Phlex API, static CSS, focused tests, exhaustive examples, and no dependency on a legacy helper.
+
+## Stage 4 — Rails and Hotwire proof
+
+Ticket: `nk-19gd`
+
+- Exercise `form_with` directly from Phlex using `NitroKit::FormBuilder`.
+- Prove route helpers, DOM ID helpers, CSRF behavior, model errors, submit paths, and multipart forms.
+- Render Turbo Frames and Turbo Streams from direct-Phlex pages.
+- Add one small validation submit path that demonstrates the real request/response loop.
+- Document the supported Rails boundary and show examples without introducing Nitro view helpers.
+
+Gate: Rails supplies framework semantics while Phlex remains the only general UI composition language.
+
+## Stage 5 — gallery infrastructure and exhaustive combinations
+
+Tickets: `nk-q4mj`, `nk-put2`, `nk-jp63`, `nk-5028`, `nk-t23x`, `nk-rtwj`, `nk-8mh8`, `nk-t66i`, `nk-vnwu`
+
+- Keep one explicit catalog of component, block, and flow entries.
+- Render the shell, pages, sections, examples, samples, and notes in Phlex.
+- Pair every preview with highlighted, copyable Ruby extracted from the exact rendering block or concrete flow method.
+- Generate route contract tests from the catalog.
+- Assert every subject has stable Nitro identities and no `class`, `style`, or escape markers.
+- Add meaningful Cartesian coverage without mechanically showing nonsense combinations.
+
+Required pressure cases:
+
+- All closed variants and sizes.
+- Default, hover/focus-capable, disabled, readonly, invalid, empty, loading-like, open, and selected states where meaningful.
+- Short, long, wrapped, numeric, missing-image, and high-item-count content.
+- Nested atoms and compound slots.
+- Light and dark themes.
+- Narrow and wide viewports.
+- Forms, tables, overlays, and navigation used together rather than only in isolation.
+
+Gate: every catalog entry succeeds through an explicit route and the gallery itself requires no Tailwind or ERB templates.
+
+## Stage 6 — atom-only product flows
+
+Tickets: `nk-31ne`, `nk-7d05`, `nk-q37g`, `nk-tcig`, `nk-32vc`
+
+Build realistic screens before inventing layout abstractions:
+
+- Authentication, registration, password reset, and verification.
+- Onboarding progress, validation, resume, and completion.
+- Dashboard overview, statistics, recent records, and activity.
+- Profile, preferences, account, and destructive settings.
+- Billing plans, payment methods, invoices, and upgrade states.
+- Users search, filters, pagination, empty state, and detail.
+- Team members, invitations, roles, and removal confirmation.
+- API credential empty, create, reveal-once, list, and revoke states.
+
+Use deterministic PORO data and explicit state slugs. Record repeated layout and responsibility friction in `notes/block_candidates.md`; do not abstract a one-off screen.
+
+Gate: all required product states exist using atoms and plain Phlex composition, and repeated structures are backed by concrete evidence.
+
+## Stage 7 — evidence-driven layouts and blocks
+
+Tickets: `nk-okls`, `nk-bjv5`, `nk-b8eg`
+
+Extract the smallest vocabulary that removes proven repetition. The evidence pass accepted:
+
+- Layouts: VStack, HStack, the three-column Grid, and Container.
+- Shell: AuthShell.
+- Sections and blocks: SettingsLayout, Toolbar, PaginationBar, PageHeader, StatGrid, DataSection, FormSection, DangerZone, and EmptyState.
+
+This list records the first extraction decision. It has since been superseded: `VStack` and `HStack` were removed in favor of unified responsive `Flex`, and the fixed three-column Grid became a responsive 1–12-column `Grid`. See the canonical specification and component contracts for the current API.
+
+At that stage, the evidence pass deferred Spacer, Split, Frame, AppShell, MarketingShell, AuthenticationPanel, and ProgressSteps because their responsibilities were not stable across enough domains. A later application-layout mandate supplied enough evidence to accept AppShell; the other deferred candidates remain outside 2.0. The settled contracts, rather than this historical stage record, live in [`agent_native_spec.md`](agent_native_spec.md) and [`component_contracts.md`](component_contracts.md).
+
+Each abstraction must:
+
+- Have one clear responsibility.
+- Use closed layout options.
+- Own only structure that actually repeats.
+- Accept atoms/content through direct Ruby composition.
+- Emit classless self-describing markup.
+- Include examples showing reuse in at least two flows.
+
+Then rewrite the atom-only flows with blocks and compare the result. Delete abstractions that do not make application code meaningfully clearer.
+
+Gate: flow code describes product intent, while layouts and blocks remain a small coherent vocabulary rather than a second page framework.
+
+## Stage 8 — expanded application gallery
+
+Tickets: `nk-pmcn`, `nk-q1tc`, `nk-oi4y`, `nk-gn4s`, `nk-ky42`
+
+Extend the block-based gallery across:
+
+- Data detail, activity, audit, uploads, and integrations.
+- Billing, authentication, onboarding, team, and API states.
+- System error, permission, empty, loading-like, and marketing states.
+- Changelog, support, and help experiences.
+
+Prefer depth of state over disconnected decorative pages. Each flow should show success, empty/error, destructive/confirmation, and constrained-width behavior where applicable.
+
+Gate: the gallery demonstrates that the vocabulary can build a credible Rails product, not only isolated controls.
+
+## Stage 9 — remove the old system
+
+Ticket: `nk-u534`
+
+- Delete all `nk_*` view helpers and automatic variant aliases.
+- Delete copied-component generators, schemas, manifests, and installation paths.
+- Delete the Action View/template capture bridge and legacy builder path.
+- Remove Tailwind Merge and consumer Tailwind dependencies.
+- Remove legacy ERB test pages, Tailwind assets, and obsolete tests.
+- Audit packaged gem files and runtime dependencies.
+
+Gate: repository-wide searches find no public legacy invocation, copied-source promise, internal component class string, or required Tailwind runtime.
+
+## Stage 10 — browser behavior and lifecycle verification
+
+Tickets: `nk-352j`, `nk-6ivz`, `nk-gxwn`, `nk-lij5`, `nk-tkds`
+
+- Enumerate every catalog URL and state in a real browser.
+- Exercise keyboard order, arrows, Escape, Enter/Space, tab trapping/return, and focus visibility.
+- Exercise open/close, select, filter, validation, submit, and destructive confirmation paths.
+- Navigate through Turbo Drive, Frames, Streams, and morph refreshes; look for duplicate controllers and leaked listeners/positioners/timers.
+- Review representative pages at narrow/wide sizes and light/dark themes.
+- Check for horizontal overflow, clipped overlays, unstable layout, unreadable content, and broken focus state.
+
+Gate: browser coverage proves both route completeness and interaction lifecycle behavior.
+
+## Stage 11 — release-quality consolidation
+
+Tickets: `nk-g3qu`, `nk-obb7`
+
+- Reconcile actual component APIs with `docs/component_contracts.md` and `STYLE_GUIDE.md`.
+- Document Rails integration, theming tokens, composition, subclass caveats, and the escape hatch.
+- Run a data-structure review for duplicated collections, scattered state, and invalid intermediate states.
+- Run a simplification pass and remove compatibility branches, duplicate validation, dead CSS, dead JavaScript, and unused dependencies.
+- Audit all CSS selectors for zero specificity and owner scoping.
+- Audit all controllers for disconnect cleanup and Turbo safety.
+- Run the complete test, lint, format, CSS build/check, package, route, and browser suites.
+
+Gate: every child of `nk-rzxf` is closed with evidence and the repository contains one coherent 2.0 architecture.
+
+## Stage 12 — deterministic agent installation
+
+Ticket: `2an-5ayl`
+
+- Ship concise Nitro Kit Rails, Hotwire, and UI skills that resolve the
+  installed gem before acting.
+- Add a setup-only generator that installs the skills for Codex and Claude and
+  maintains a bounded `AGENTS.md` section without copying component source.
+- Add diagnostics for the resolved version, agent guidance, Hotwire wiring,
+  Phlex Kit inclusion, stylesheet loading, and Nitro Kit 1.x shadows.
+- Print or copy an initialization prompt without launching an agent.
+- Make guided and Pro eval profiles run the real installer and name Nitro Kit
+  2.x explicitly; retain cold profiles for diagnostic comparisons.
+
+Gate: installation is idempotent, preserves application-owned instructions,
+routes agents to version-matched doctrine, and is exercised by the eval
+harness.
+
+## Verification matrix
+
+| Surface       | Required verification                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------- |
+| Ruby API      | Focused construction/render tests; invalid vocabulary; missing content; reserved attributes       |
+| Markup        | Native semantics; stable IDs; ARIA relationships; `data-nk`; qualified `data-slot`; visible state |
+| CSS           | Deterministic build/check; zero-specificity owner-scoped selectors; token audit; light/dark       |
+| Rails         | Real `form_with`; Active Model; routes/DOM IDs; multipart; validation submit; Frame/Stream        |
+| JavaScript    | Keyboard behavior; open/close/select; disconnect cleanup; Turbo navigation and morph              |
+| Gallery       | Catalog routes; exact escaped source; copy behavior; no class/style/escape; narrow/wide           |
+| Packaging     | Engine boot with optional integrations absent; gem contents and dependencies audited              |
+| Documentation | Specification, contracts, style guide, Rails boundary, theming, examples, repository commands     |
+
+## Execution and handoff
+
+Use `tk ready` to select dependency-safe work. Preparatory parallel work is permitted only when the orchestrator explicitly assigns non-overlapping ownership. Every handoff names changed files, behavior decisions, focused test counts, and known failures. The orchestrator independently reviews and reproduces meaningful checks before closing a feature ticket.

data/docs/initialization_prompt.md

@@ -0,0 +1,36 @@
+# Initialize Nitro Kit 2 in this Rails application
+
+Finish the application-specific Nitro Kit 2 setup. Do not use Nitro Kit 1.x
+APIs or examples.
+
+1. Run `bundle show nitro_kit` and confirm the resolved version begins with
+   `2.`.
+2. Read `docs/agent_guide.md` from that installed gem, then read the locally
+   installed `nitro-kit-rails`, `nitro-kit-hotwire`, and `nitro-kit-ui` skills.
+3. Inspect the application before editing. Preserve established application
+   conventions unless they conflict with the requested Nitro Kit 2 setup.
+4. Ensure an application base Phlex component includes `NitroKit` once and
+   product components inherit from it.
+5. Re-run `bin/rails generate nitro_kit:install`. Ensure its application layout
+   setup has one appearance bootstrap before every stylesheet, then optional
+   third-party base styles, the optional Tailwind adapter, `nitro_kit`, compiled
+   Tailwind, and application token overrides in that order. Add flash toast
+   rendering when the application uses it.
+6. Ensure Turbo and Stimulus are wired and the normal Stimulus loader can
+   discover the gem-owned `nk--*` controllers. Never copy Nitro components,
+   helpers, or controllers into the application.
+7. Remove confirmed Nitro Kit 1.x shadows such as application-owned
+   `NitroKit` components, `nk_*` helpers, or `controllers/nk` only when this
+   task is authorized to migrate the application.
+8. Use ordinary Rails routes, models, forms, and server-rendered HTML. Follow
+   the installed Rails and Hotwire guidance for new work. During a migration,
+   replace an existing control only when Nitro Kit 2 has a genuine semantic
+   and behavioral equivalent. Otherwise preserve it as application-owned
+   Rails and semantic HTML; never downgrade specialized behavior or retain
+   copied Nitro Kit 1.x source as the fallback.
+9. Run `bin/rails nitro_kit:doctor`, fix actionable failures, and run the
+   application's relevant tests.
+
+Report what you changed, any existing convention you deliberately preserved,
+any unsupported control recorded as a Nitro Kit coverage gap, and any warning
+that still needs a product decision.

data/docs/migration_1_to_2.md

@@ -0,0 +1,318 @@
+# Migrating a Nitro Kit 1.x application
+
+Treat a 1.x migration as a product-flow review, not a helper rename. Nitro Kit
+2 deliberately removed copied components, `nk_*` helpers, application-owned
+`controllers/nk`, and unrestricted utility-class customization.
+
+## Install the 2.0 alpha before migrating
+
+Add the 2.0 alpha prerelease to the application's Gemfile:
+
+```ruby
+gem "nitro_kit", "2.0.0.alpha.1"
+```
+
+Bundler records the exact released version in `Gemfile.lock`; commit `Gemfile`
+and `Gemfile.lock` together. Before upgrading during the migration, review the
+changelog, run `bundle update nitro_kit`, rerun the installer and doctor, and
+exercise the converted flows before committing the updated lockfile.
+Production applications should use the released gem and a committed lockfile
+rather than a moving Git branch.
+
+## Inventory behavior before editing
+
+1. List every `nk_*` helper, `NitroKit::*` component, copied Nitro source file,
+   and `controllers/nk` controller.
+2. Group usage by user flow: authentication, settings, collection browsing,
+   mobile navigation, editing, destructive actions, notifications, and
+   copy/share controls.
+3. Record behavior that must survive: native element, submitted method and
+   parameters, Turbo target, accessible name and description, focus behavior,
+   narrow-screen presentation, empty/error state, and visual density.
+4. Capture representative wide and narrow screenshots before conversion.
+
+If the Nitro Kit MCP catalog is connected, search it by workflow after this
+inventory — for example `mobile transcript navigation`, `settings form`, or
+`empty query results`. Do not search only for an old component name. MCP can
+deliver complete compositions; the installed gem remains the authority for
+the free component contract.
+
+## Select semantics before atoms
+
+Map each flow to the highest-level matching 2.x component first:
+
+| Existing need                           | Begin with                              |
+| --------------------------------------- | --------------------------------------- |
+| Sign-in or recovery card                | `AuthShell`                             |
+| Application navigation                  | `AppShell`, `AppNavigation`             |
+| Mobile contextual navigation or details | `Sheet`                                 |
+| Settings screen                         | `SettingsLayout`, `FormSection`         |
+| Empty collection card                   | `EmptyState`                            |
+| Data collection                         | `DataSection`, `Table`, `PaginationBar` |
+| Destructive settings                    | `DangerZone`, `Dialog`, `ButtonTo`      |
+| Joined copy or filter controls          | `ControlGroup`                          |
+
+Only then replace remaining atoms. Common direct mappings include:
+
+- `nk_button_link_to` → `NitroKit::Button.new(..., href:)`
+- `nk_button_to` → `NitroKit::ButtonTo.new(..., href:, method:)`
+- `nk_form_with` → Rails `form_with(..., builder: NitroKit::FormBuilder)`
+- block-wrapped tooltips → a linked Button trigger or Tooltip `as: :custom`
+- copied mobile Sidebar → `Sheet`, not a plain disclosure
+
+Do not preserve a Card merely because 1.x used one. Empty states,
+authentication shells, settings regions, and data sections have stronger
+semantics and more useful responsive behavior.
+
+## Move ERB collections and yielded content into compound declarations
+
+The ERB below is representative application-owned migration input, not a
+Nitro Kit 2 API. Nitro Kit 2 has no ERB component bridge. Move the collection
+to the Phlex component, then declare entries only inside their owning compound
+region. Content formerly yielded by a partial belongs directly inside the
+matching `panel` or `content` block.
+
+### AppNavigation
+
+ERB source — the call site owns the destination collection and the partial
+iterates it:
+
+```erb
+<% destinations = [["Home", root_path], ["Projects", projects_path]] %>
+<%= render "app_navigation", label: "Primary", destinations: destinations %>
+
+<%# _app_navigation.html.erb %>
+<nav aria-label="<%= label %>">
+  <ul>
+    <% destinations.each do |text, href| %>
+      <li><%= link_to text, href %></li>
+    <% end %>
+  </ul>
+</nav>
+```
+
+Phlex destination — declare the collection before `AppNavigation`; consume it
+inside the required `body` collection region:
+
+```ruby
+destinations = [["Home", root_path], ["Projects", projects_path]]
+
+render NitroKit::AppNavigation.new(label: "Primary") do |navigation|
+  navigation.body do
+    destinations.each_with_index do |(text, href), index|
+      navigation.item(text, href:, current: index.zero?)
+    end
+  end
+end
+```
+
+The executable minimal version is on the
+[`AppNavigation` gallery page](/gallery/components/app-navigation#example-app-navigation-minimal).
+
+### Dialog
+
+ERB source — the call-site block is yielded inside the partial's panel:
+
+```erb
+<%= render "dialog", id: "transcript-details", title: "Transcript details" do %>
+  <p>The transcript was recorded at 09:42 UTC.</p>
+<% end %>
+
+<%# _dialog.html.erb %>
+<button command="show-modal" commandfor="<%= id %>-panel">Details</button>
+<dialog id="<%= id %>-panel">
+  <h2><%= title %></h2>
+  <%= yield %>
+</dialog>
+```
+
+Phlex destination — trigger and panel declarations live inside `Dialog`; the
+former yielded content lives inside `panel`:
+
+```ruby
+render NitroKit::Dialog.new(id: "transcript-details") do |dialog|
+  dialog.trigger("Details")
+  dialog.panel(title: "Transcript details") do
+    p { "The transcript was recorded at 09:42 UTC." }
+  end
+end
+```
+
+Placement belongs to the parent. In the conversion that exposed this rule, a
+`Flex` containing **Redact** and **Permalink** was followed by a `Dialog`
+sibling, so the Dialog trigger started a second line. Put the Dialog root
+inside the same no-wrap action cluster:
+
+```ruby
+Flex(dir: :row, gap: 1, align: :center, wrap: :nowrap) do
+  Button("Redact", size: :sm, variant: :destructive)
+  Button("Permalink", href: transcript_path(transcript), size: :sm)
+
+  Dialog(id: dom_id(transcript, :details)) do |dialog|
+    dialog.trigger("Details", size: :sm)
+    dialog.panel(title: "Transcript details") do
+      render UI::TranscriptDetails.new(transcript)
+    end
+  end
+end
+```
+
+The gallery runs this structure at narrow widths in
+[`Narrow transcript actions`](/gallery/components/dialog#example-dialog-narrow-action-cluster).
+
+### Sheet
+
+ERB source — the partial yields contextual content into its side panel:
+
+```erb
+<%= render "sheet", id: "transcript-prompts", title: "Prompts" do %>
+  <%= render "prompts", prompts: @prompts %>
+<% end %>
+
+<%# _sheet.html.erb %>
+<button command="show-modal" commandfor="<%= id %>-panel">Prompts</button>
+<dialog id="<%= id %>-panel">
+  <h2><%= title %></h2>
+  <%= yield %>
+</dialog>
+```
+
+Phlex destination — declare the collection before `Sheet`; render it only
+inside the `panel` content slot:
+
+```ruby
+prompts = transcript.prompts.map { |prompt| [prompt.title, prompt_path(prompt)] }
+
+render NitroKit::Sheet.new(id: "transcript-prompts", side: :left) do |sheet|
+  sheet.trigger("Prompts", icon: :list)
+  sheet.panel(title: "Transcript prompts") do
+    render NitroKit::AppNavigation.new(label: "Transcript prompts") do |navigation|
+      navigation.body do
+        prompts.each do |text, href|
+          navigation.item(text, href:)
+        end
+      end
+    end
+  end
+end
+```
+
+See the executable
+[`Sheet` collection example](/gallery/components/sheet#example-sheet-constructions).
+
+### SettingsLayout
+
+ERB source — the call site supplies both the navigation collection and yielded
+settings content:
+
+```erb
+<% sections = [["Profile", profile_settings_path], ["Security", security_settings_path]] %>
+<%= render "settings_layout", sections: sections do %>
+  <%= render "profile_form" %>
+<% end %>
+
+<%# _settings_layout.html.erb %>
+<nav aria-label="Settings">
+  <% sections.each do |text, href| %>
+    <%= link_to text, href %>
+  <% end %>
+</nav>
+<main><%= yield %></main>
+```
+
+Phlex destination — navigation entries stay inside `navigation`; the former
+yield lives inside the one `content` region:
+
+```ruby
+sections = [["Profile", profile_settings_path], ["Security", security_settings_path]]
+
+render NitroKit::SettingsLayout.new do |layout|
+  layout.navigation(label: "Settings") do
+    sections.each_with_index do |(text, href), index|
+      layout.item(text, href:, current: index.zero?)
+    end
+  end
+  layout.content { render UI::ProfileForm.new(profile) }
+end
+```
+
+See the executable
+[`SettingsLayout` minimal example](/gallery/components/settings-layout#example-settings-layout-cardinality-states).
+
+## Preserve unsupported behavior honestly
+
+When no equivalent exists, keep semantic Rails or HTML under the application
+namespace and report the missing capability. Do not retain copied 1.x source,
+downgrade a specialized control, or hide the gap behind a generic component.
+
+Tooltip custom triggers are the explicit composition path for an existing
+focusable control. Forward every yielded boundary to that actual control:
+
+```ruby
+render NitroKit::Tooltip.new(id: "revoke-help", content: "Revokes access immediately") do |tooltip|
+  tooltip.trigger(as: :custom) do |attributes|
+    render NitroKit::ButtonTo.new(
+      "Revoke",
+      href: token_path(token),
+      method: :delete,
+      variant: :destructive,
+      button_html: attributes.html,
+      button_aria: attributes.aria,
+      button_data: attributes.data
+    )
+  end
+end
+```
+
+## Verify fidelity
+
+Install and run Nitro Kit's focused host-integration acceptance flow:
+
+```sh
+bin/rails generate nitro_kit:upgrade_smoke_tests
+bin/rails test test/integration/nitro_kit_upgrade_smoke_test.rb
+bin/rails test test/system/nitro_kit_upgrade_smoke_test.rb
+```
+
+The generator does not overwrite existing tests. It generates only files
+supported by the host's Rails Minitest and system-test setup and prints setup
+guidance for skipped files. The tests use the currently bundled gem and cover
+the shared upgrade boundary — browser-submitted Turbo validation and mutation,
+Dialog and Sheet, layout-owned Rails flash, Turbo Frame identity, redirects,
+and post-mutation Phlex rendering. Their collision-checked route exists only
+during each test and is restored afterward; they add no production route or
+component source. Keep application-specific migration tests for inventoried
+product behavior alongside them.
+
+The endpoint deliberately inherits `ApplicationController` callbacks. If the
+application requires authentication or current-account state, fill in the
+generated `prepare_nitro_kit_upgrade_smoke_test` methods with the same sign-in
+and account-selection helpers used by ordinary integration and system tests.
+Extend those application-owned classes rather than changing gem test support
+or skipping host callbacks.
+
+Run focused request and component tests, then compare the converted flows in a
+browser at wide and narrow widths. Exercise keyboard focus, dialogs and sheets,
+Turbo submissions, errors, empty states, light/dark appearance, and dense
+metadata. A green request suite does not prove that a tooltip, off-canvas
+panel, interactive Card treatment, or responsive composition survived.
+
+Finish by deleting copied components, helpers, and controllers; run
+`bin/rails nitro_kit:doctor`; and record every remaining application-owned
+fallback as either intentional product UI or a Nitro Kit coverage gap.
+
+Doctor inventories only concrete Nitro Kit 1.x conventions: `nk_*` helpers,
+generated files under `app/components/nitro_kit`, controllers under
+`app/javascript/controllers/nk`, the old Floating UI and combobox packages,
+and `tailwind_merge`. Every finding includes a file and replacement. Its
+disposition is:
+
+- `migrated` — no remaining occurrence in that category.
+- `unresolved` — a known 1.x integration still needs its documented 2.x
+  replacement or removal.
+- `application-owned` — custom or unsupported behavior must be preserved under
+  an application namespace, not as a Nitro shadow.
+
+The inventory deliberately does not guess from generic component, JavaScript,
+or dependency names. Review application-owned product behavior separately and
+keep its migration record with the application.

data/docs/new_app_strategy.md

@@ -0,0 +1,24 @@
+# New application strategy
+
+Recommend a Rails application template for new applications, not a return to Nitro Kit's old component-copying generator.
+
+Rails application templates are designed to configure a new app during `rails new`, can add gems, and can run generators after Bundler finishes. That gives Nitro Kit an eventual one-command entry point:
+
+```sh
+rails new my_app -m https://nitrokit.dev/template.rb
+```
+
+The template should remain thin while the conventions settle. Its first
+version should add Nitro Kit and invoke `nitro_kit:install`. The generator owns
+the project-local skills and `AGENTS.md`; the template may add an application
+layout that renders the stylesheet, appearance bootstrap, and flash toasts. It
+must not copy Nitro components or their controllers.
+
+Existing applications install the gem directly and run the setup generator.
+Agent discovery, version-matched skill routing, diagnostics, and initialization
+handoff are meaningful application-owned setup; component source remains
+gem-owned.
+
+An optional `nitro_kit:application` generator can later create an application-owned base: layout, `UI` namespace, shell choice, root screen, and authentication hooks. Keep that separate from installing the UI gem so teams can adopt Nitro Kit without adopting an application architecture.
+
+Promote the template into a versioned starter application only when Nitro Kit deliberately owns opinions beyond UI and interaction conventions, such as authentication, accounts, teams, billing, jobs, mail, and deployment. Until then, the application template is easier to inspect, test, and evolve and does not impose the maintenance cost of a forked starter repository.