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

data/docs/hotwire.md

@@ -1,94 +1,68 @@
 # Hotwire with Nitro Kit
 
-Nitro Kit owns component markup, CSS, and its focused progressive controllers.
-Rails owns records, routes, authorization, queries, DOM identity, and server
-responses. Hotwire transports server-rendered HTML between those boundaries.
+**Audience:** Application developers and coding agents implementing Hotwire
+interactions with Nitro Kit.
 
-## Choose the smallest interaction
-
-1. Use ordinary links and forms under Turbo Drive.
-2. Use a Turbo Frame for one independently navigable or replaceable region.
-3. Return request-scoped Turbo Streams when one action changes multiple
-   regions.
-4. Broadcast only when another session needs the update.
-5. Add application Stimulus only for browser-owned behavior the preceding
-   layers cannot express.
-
-Do not copy Nitro Kit controllers into the application. Do not add files under
-`app/javascript/controllers/nk`; consume the `nk--*` controllers packaged by
-the installed gem.
-
-## Response matrix
+Rails owns records, routes, authorization, DOM identity, and responses. Nitro
+Kit owns component markup, CSS, and its focused controllers. Hotwire transports
+server-rendered HTML between them.
 
-| Request              | Success                                       | Invalid or denied                                                   |
-| -------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
-| HTML form mutation   | Redirect with `303 See Other`                 | Render HTML with `422`                                              |
-| Frame form mutation  | Redirect or render the same frame ID          | Render the same frame ID with `422`                                 |
-| Stream form mutation | Return only when multiple targets must change | Render the invalid form target with `422` and keep an HTML fallback |
-| GET query            | Render from URL parameters                    | Render a useful empty or error state                                |
-
-Use `dom_id` or one named constant for a frame. The show, edit, invalid,
-success, and cancel responses must preserve that identifier.
-
-## Forms and application Stimulus
+## Choose the smallest interaction
 
-Let Turbo submit real Rails forms. Use `data-turbo-submits-with` to opt a Button
-into submission feedback without replacing its visible label. The Button dims
-immediately; `submission_indicator: :spinner` additionally reveals an indicator
-after 1 second and lets the Button expand to fit it. Use `data-turbo-confirm` for
-compact destructive confirmation.
-Reviewed destructive flows may compose `DangerZone` and `Dialog`, but the
-dialog must still submit a real Rails form.
+1. Ordinary links and forms under Turbo Drive.
+2. One Turbo Frame for one independently navigable region.
+3. A request-scoped Turbo Stream when one action changes multiple regions.
+4. A broadcast only when another session needs the update.
+5. Application Stimulus only for browser-owned behavior the previous layers
+   cannot express.
 
-Keep application controllers small, declarative, and disposable. For a
-self-submitting control, the complete controller can be:
+Do not copy Nitro controllers or add files under
+`app/javascript/controllers/nk`. Follow the canonical
+[browser support policy](browser_support.md) for fallback behavior.
 
-```js
-import { Controller } from "@hotwired/stimulus";
+## Response contract
 
-export default class extends Controller {
-  submit() {
-    this.element.requestSubmit();
-  }
-}
-```
+| Request         | Success                                   | Validation failure                                              |
+| --------------- | ----------------------------------------- | --------------------------------------------------------------- |
+| HTML mutation   | Redirect with `303 See Other`             | Render the invalid form with `422`                              |
+| Frame mutation  | Redirect to, or render, the same frame ID | Render the same frame ID with `422`                             |
+| Stream mutation | Return a stream only for multiple targets | Replace the invalid form target with `422`; keep an HTML branch |
+| GET query       | Render from URL parameters                | Render a useful empty or error state                            |
 
-Attach `data-action="change->auto-submit#submit"` to the form so change events
-bubble to that one controller root. Keep a submit button inside `noscript` as
-the HTML fallback. Use `data-action` instead of manually registering DOM listeners. If a
-controller owns a listener, observer, timer, object URL, or third-party
-instance, release it in `disconnect`.
+Authentication and authorization failures are separate policy decisions; do
+not return `422` for them.
 
-## Morphing and cache lifecycle
+Use `dom_id` or one named constant for each frame. Show, edit, invalid, success,
+and cancel responses must preserve that identifier. An HTML branch preserves
+the request path without Turbo; it does not make a closed or JavaScript-owned
+interaction available.
 
-Default to morphable server-rendered HTML. Use `data-turbo-permanent` only for
-a genuinely stateful island, always with a stable unique `id`. Update content
-inside a permanent element deliberately instead of making broad page regions
-permanent.
+## Stimulus and lifecycle
 
-Clean ephemeral UI before Turbo caches the page. Nitro Kit controllers own
-their own cache and reconnect behavior; application controllers must do the
-same for application-owned state.
+Let Turbo submit real Rails forms. Use `data-turbo-submits-with` for submission
+feedback and `data-turbo-confirm` only for compact confirmation. A reviewed
+destructive flow still submits a real Rails form; use the
+[destructive action pattern](patterns/destructive_action.md).
 
-## Frame escape and recovery
+Keep application controllers declarative. Prefer `data-action` over manually
+registered listeners. Release listeners, observers, timers, object URLs, and
+third-party instances in `disconnect`.
 
-An authentication redirect or error response inside a frame must not strand
-the user behind a missing-frame error. Use `_top` when navigation must leave
-the frame. Keep authentication and authorization handling capable of returning
-a full-page response, and handle `turbo:frame-missing` only when the
-application has a deliberate recovery policy.
+Keep server-rendered markup morph-safe. Enable refresh morphing deliberately,
+and use `data-turbo-permanent` only for a stateful island with a stable unique
+ID. Clean ephemeral UI before Turbo caches a page.
 
-Give lazy frames meaningful loading content. A failed frame should leave an
-understandable state and a path to retry or continue without JavaScript.
+Use `_top` when navigation must leave a frame. Authentication redirects and
+errors must not strand the user behind a missing-frame response. Give lazy and
+failed frames useful content and a route to continue.
 
-## Verify behavior
+## Verify
 
 - Request-test `303`, `422`, HTML fallback, and stable frame IDs.
-- On mutation responses, assert submitted content inside the response's
-  matching frame, not merely somewhere in the response body.
-- System-test focus, dialogs, frame navigation, and multi-target changes.
-- Use Capybara assertions that wait for the DOM; never use `sleep`.
-- Test navigation, morphing, and reconnection without duplicating controller
-  roots or listeners.
-
-Read the matching recipe under `docs/patterns/` for complete compositions.
+- Scope mutation assertions to the matching frame.
+- System-test focus, navigation, dialogs, and multi-target changes.
+- Use Capybara waiting assertions; never use `sleep`.
+- Test navigation, caching, morphing, and reconnection for duplicate state or
+  listeners.
+
+Use the matching [interaction pattern](patterns/) for complete compositions.

data/docs/initialization_prompt.md

@@ -1,36 +1,31 @@
-# Initialize Nitro Kit 2 in this Rails application
+# Verify Nitro Kit 2 setup in this Rails application
 
-Finish the application-specific Nitro Kit 2 setup. Do not use Nitro Kit 1.x
-APIs or examples.
+**Audience:** Coding agent running immediately after Nitro Kit installation.
 
-1. Run `bundle show nitro_kit` and confirm the resolved version begins with
+1. Run `bundle show nitro_kit` and confirm the resolved version starts 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
+2. Choose the project-local Nitro Kit skill matching the task. It will resolve
+   and read the installed, version-matched `docs/agent_guide.md`.
+3. Inspect the application before editing. Preserve established view, asset,
+   authentication, and testing conventions unless the task changes them.
+4. For a greenfield application, run `bin/rails generate phlex:install` and use
+   Phlex for the application layout, route views, and reusable UI. In an
+   established application, introduce Phlex only at the requested boundary.
+   Do not perform an application-wide migration unless it is explicitly
+   authorized.
+5. Verify that the application loads Nitro Kit CSS, the appearance bootstrap,
+   Turbo, Stimulus, and the normal Stimulus controller loader. Never copy Nitro
+   components or `nk--*` controllers into the application.
+6. Verify one application base component includes `NitroKit`, and model-backed
+   forms select `NitroKit::FormBuilder` explicitly.
+7. 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.
+If this is a Nitro Kit 1.x migration, stop and follow
+`docs/migration_1_to_2.md` from the installed gem. Replace a control only when
+2.x provides a genuine semantic and behavioral equivalent. Otherwise preserve
+it as application-owned Rails and semantic HTML. Never retain copied Nitro Kit
+1.x source as the fallback.
+
+Report changes, preserved conventions, unsupported controls, and unresolved
+decisions.

data/docs/migration_1_to_2.md

@@ -1,15 +1,18 @@
 # Migrating a Nitro Kit 1.x application
 
+**Audience:** Coding agents and developers migrating an existing application
+from Nitro Kit 1.x to 2.x.
+
 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
+## Install the 2.0 prerelease before migrating
 
-Add the 2.0 alpha prerelease to the application's Gemfile:
+Add the 2.0 prerelease to the application's Gemfile:
 
 ```ruby
-gem "nitro_kit", "2.0.0.alpha.2"
+gem "nitro_kit", "2.0.0.alpha.4"
 ```
 
 Bundler records the exact released version in `Gemfile.lock`; commit `Gemfile`
@@ -22,14 +25,19 @@ 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.
+   `controllers/nk` controller, rendered native or Rails button helper, and
+   application-owned button class such as `.btn`.
 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.
+4. Inventory the existing semantic primary, focus, destructive, neutral, font,
+   density, and radius decisions. Translate those roles to public `--nk-*`
+   tokens rather than choosing similar raw palette values. Record separately
+   when buttons use a distinct shape from inputs and surfaces.
+5. 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
@@ -46,11 +54,12 @@ Map each flow to the highest-level matching 2.x component first:
 | Sign-in or recovery card                | `AuthShell`                             |
 | Application navigation                  | `AppShell`, `AppNavigation`             |
 | Mobile contextual navigation or details | `Sheet`                                 |
-| Settings screen                         | `SettingsLayout`, `FormSection`         |
+| Settings screen                         | `SettingsLayout`, `SettingsSection`     |
 | Empty collection card                   | `EmptyState`                            |
 | Data collection                         | `DataSection`, `Table`, `PaginationBar` |
 | Destructive settings                    | `DangerZone`, `Dialog`, `ButtonTo`      |
 | Joined copy or filter controls          | `ControlGroup`                          |
+| Joined action controls                  | `ButtonGroup`                           |
 
 Only then replace remaining atoms. Common direct mappings include:
 
@@ -107,7 +116,7 @@ end
 ```
 
 The executable minimal version is on the
-[`AppNavigation` gallery page](/gallery/components/app-navigation#example-app-navigation-minimal).
+[`AppNavigation` gallery page](https://gallery.nitrokit.dev/gallery/components/app-navigation#example-app-navigation-minimal).
 
 ### Dialog
 
@@ -158,7 +167,7 @@ end
 ```
 
 The gallery runs this structure at narrow widths in
-[`Narrow transcript actions`](/gallery/components/dialog#example-dialog-narrow-action-cluster).
+[`Narrow transcript actions`](https://gallery.nitrokit.dev/gallery/components/dialog#example-dialog-narrow-action-cluster).
 
 ### Sheet
 
@@ -198,7 +207,7 @@ end
 ```
 
 See the executable
-[`Sheet` collection example](/gallery/components/sheet#example-sheet-constructions).
+[`Sheet` collection example](https://gallery.nitrokit.dev/gallery/components/sheet#example-sheet-constructions).
 
 ### SettingsLayout
 
@@ -237,13 +246,22 @@ end
 ```
 
 See the executable
-[`SettingsLayout` minimal example](/gallery/components/settings-layout#example-settings-layout-cardinality-states).
+[`SettingsLayout` minimal example](https://gallery.nitrokit.dev/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.
+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, preserve the unsupported behavior in clearly application-owned
+code, and report the missing equivalent as a Nitro Kit coverage gap. Do not
+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:
@@ -276,13 +294,19 @@ 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.
+guidance for skipped files. Keep the generated explanatory header in each
+test: these are host-integration regression checks, not substitutes for
+application-specific acceptance tests. Run every supported generated test
+before and after the application conversion, while retaining
+application-specific acceptance coverage for every inventoried flow.
+
+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 route is prepended only during each test, so host
+catch-all routes remain compatible; an exact GET or PATCH route at the same
+path is still rejected rather than masked. The route is restored afterward and
+adds no production route or component source.
 
 The endpoint deliberately inherits `ApplicationController` callbacks. If the
 application requires authentication or current-account state, fill in the
@@ -291,20 +315,52 @@ 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,
+Run focused request and component tests, then compare the converted flows
+across the dated matrix in `docs/browser_support.md`, including Mobile Safari
+where available, 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
+metadata. Inspect computed styles for missing application classes, stacked
+Button content, broken compound corners, double focus rings, clipping, and
+theme drift. 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,
+fallback as either intentional product UI or a Nitro Kit coverage gap. Use
+`bin/rails nitro_kit:doctor --format=json` when migration automation needs
+stable `status`, `label`, and `detail` fields.
+
+Before declaring the migration complete, search for every
+`desperately_need_a_class:` use and review each one. Aim for zero. Move layout,
+spacing, width, responsive positioning, and application colors to an
+application-owned wrapper; use documented component options and native
+attributes for semantics and state; accept Nitro defaults where the difference
+is incidental; and keep specialized controls or navigation application-owned
+when Nitro is not the right abstraction. Remove generic class forwarding from
+shared builders. A scoped wrapper rule may target ordinary descendant elements
+when the application truly owns that layout behavior, such as fixed table
+layout. Retain the escape only when a named external integration actually
+requires a class hook, and document why.
+
+For such a retained integration, `desperately_need_a_class:` accepts Rails-style
+strings, symbols, nested arrays, or conditional hashes without manual
+`compact.join(" ")` formatting. A Tailwind application may use its own
+Tailwind-aware merger when that hook needs conflicting utility classes
+resolved. Nitro does not require the dependency because its own component CSS
+is static and classless.
+
+Doctor inventories 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
+`app/javascript/controllers/nk`, and the old Floating UI and combobox packages.
+When application CSS defines a `.btn` treatment, Doctor
+also records rendered `btn` class usages as application-owned review work; it
+does not assume every specialized control should become a Nitro Button. Doctor
+also uses Ruby syntax trees to catch provable 2.0 runtime violations: direct
+`id:` keywords on Table compound methods and statically icon-only
+`NitroKit::Button`, Dropdown trigger, and Sheet trigger declarations without an
+accessible name. Rendering remains
+the final authority for dynamic wrappers and delegated component declarations.
+Every finding includes a file and replacement or review instruction. Its
 disposition is:
 
 - `migrated` — no remaining occurrence in that category.
@@ -314,5 +370,7 @@ disposition is:
   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.
+or dependency names beyond a button treatment the application itself defines.
+Review application-owned product behavior separately and keep its migration
+record with the application. Re-audit native buttons, Rails button helpers, and
+application-owned button classes after Doctor is otherwise clean.

data/docs/patterns/application_foundation.md

@@ -1,136 +1,62 @@
-# A durable application foundation
+# Application foundation
 
-Start a small authenticated application with the same records and page grammar
-it will need after the second person joins. The first-user case should be the
-smallest instance of the team model, not a separate personal mode that must be
-replaced later.
+**Audience:** Coding agents and developers starting an authenticated,
+team-aware Nitro Kit application.
 
 ## Summary
 
-- Model `User`, `Team`, and `Membership` from the first signup; role belongs to
-  `Membership`, and every team-owned record loads through `Current.team`.
-- One hybrid `AppShell` frames the authenticated product: `AppNavigation` owns
-  brand and destinations, the shell `Toolbar` owns route titles and persistent
-  basic actions.
-- One wrapper immediately inside `shell.main` owns responsive page padding for
-  every route; the shell owns viewport height and scrolling.
-- Infrequent account destinations go after `navigation.spacer`; settings
-  compose with `SettingsLayout` and plain `FormSection` regions.
-- When destination count warrants search, compose one `CommandPalette` in the
-  shell and render only routes the current membership may visit.
-- Centralize cross-cutting feedback in one flash-driven toast region rendered
-  by the layout.
+- Model `User`, `Team`, and `Membership`; roles belong to memberships, and
+  tenant-owned records load through `Current.team`.
+- Use one `AppShell` for the authenticated product and one application-owned
+  content gutter inside `shell.main`.
+- Put route titles and persistent actions in the shell `Toolbar`; keep
+  destinations in `AppNavigation`.
+- Use links for settings destinations and one layout-level
+  `Toast::FlashMessages` region for server feedback.
 
-## Use memberships from the first user
-
-Use `User`, `Team`, and `Membership` even when signup creates exactly one of
-each. Put the role on `Membership`, not `User`, because authority belongs to a
-person's relationship with a team. Create the first team and owner membership
-in the same transaction as signup.
+## Membership and current context
 
+Create the first team and owner membership in the same transaction as signup.
 Set `Current.user`, `Current.membership`, and `Current.team` from the session.
-Load every team-owned record through `Current.team`; use `Current.user` for
-authorship and audit fields. Start with the smallest role vocabulary the
-product needs, usually owner, administrator, and member. Protect the last owner
-in the domain model rather than only hiding a button.
-
-Invitations should belong to a team, record the inviter and intended role,
-expire, match the invited email, and be consumed when accepted. An existing
-user accepts into a new membership; a new user completes signup and then uses
-the same acceptance path.
-
-## Compose one authenticated frame
-
-Use one hybrid `AppShell` for the authenticated product. Keep the brand and
-primary destinations in `AppNavigation`; place route titles and persistent
-basic actions in the shell `Toolbar`. One wrapper immediately inside
-`shell.main` owns responsive page padding for every route. The topbar and
-sidebar header should use the shell's shared height and border tokens rather
-than independent padding guesses.
-
-Put infrequent account navigation after `navigation.spacer`, near the account
-controls at the bottom of the sidebar:
-
-```ruby
-shell.navigation do
-  AppNavigation(label: "Workspace navigation") do |navigation|
-    navigation.body do
-      navigation.item("Inventory", href: assets_path, icon: :archive)
-      navigation.item("Team", href: team_path, icon: :users)
-      navigation.spacer
-      navigation.item("Settings", href: settings_profile_path, icon: :settings)
-    end
-  end
-end
-```
-
-Application code owns destinations and current-route policy. Nitro owns shell
-layout, mobile disclosure, focus management, and navigation semantics.
-For larger products, place one `CommandPalette` in the shell. Its native links
-remain the navigation authority while Command-K or Control-K adds fast
-filtering. Render the same authorized destination set the user can reach in
-ordinary navigation; do not use the palette to bypass route policy.
-When the destination set is too large or dynamic to render eagerly, pass
-`search_url:` and return `CommandPalette::Results` from that endpoint. Keep the
-same authorization scope on the initial links and every remote query.
-Let the shell own viewport height and scrolling; do not add `min-height: 100vh`
-to its main region or page wrapper. Put brand and destination icons through the
-navigation slots so they share the same left alignment.
-
-Team is an administration surface, not merely a roster. Include pending
-invitations and the complete invite, role-change, removal, and revoke paths,
-with last-owner protection in the model and authorization on every mutation.
-
-Authentication is a standalone form surface. Inside `AuthShell`, use Rails
-`form_with` with `NitroKit::FormBuilder` and put the visible fields, submit
-control, and related recovery link in one `form.group`. The group owns their
-vertical rhythm; `AuthShell` owns only the page container and spacing between
-its major regions.
+Use `Current.user` for authorship and audit fields; scope tenant data through
+the team. Protect the last owner in the model.
 
-## Keep settings plain
+Invitations belong to a team, record inviter and role, expire, and match the
+invited email. Existing and new users should share one acceptance path.
 
-Use `SettingsLayout` inside the normal shell main region. Its navigation lists
-stable subsections such as Profile, Notifications, Appearance, and Password;
-its content renders the selected form. Use `FormSection` for genuinely distinct
-form regions and ordinary whitespace or dividers between them.
+## Authenticated shell
 
-Render subsection destinations as links and mark the active link with
-`aria-current="page"`. They navigate between routes; Buttons and ButtonGroup
-would incorrectly present them as in-page actions. Small preferences may
-submit on change through a tiny application Stimulus controller that calls the
-form's native `requestSubmit`. Keep a submit control in `noscript` so the form
-still works without JavaScript.
+Use one `AppShell`, normally `layout: :hybrid`, for authenticated routes.
+`AppNavigation` owns brand and destinations; a `Toolbar` in `shell.topbar`
+owns the route's single `h1` and persistent actions. One wrapper inside
+`shell.main` owns responsive page padding. Do not add another viewport-height
+or outer-padding rule in child pages.
 
-The route still has one `h1` in the shell toolbar. Do not repeat “Settings” in
-the page body, wrap each subsection in a Card, or give every form its own outer
-padding. A toolbar Save button can submit the selected form with the native
-`form:` attribute, so the action stays in the same place at narrow and wide
-widths without JavaScript.
+Application code owns destinations, authorization, and current-route policy.
+Nitro owns responsive disclosure and focus behavior. Put infrequent account
+destinations after `navigation.spacer`. Add one `CommandPalette` only when the
+destination count warrants search, and render only authorized routes.
 
-## Centralize cross-cutting feedback
+Use `AuthShell` with Rails `form_with` and `NitroKit::FormBuilder` for
+authentication. Put visible fields, submit, and recovery link in one
+`form.group`.
 
-Render `Toast::FlashMessages` once in the application layout. Keep using
-ordinary Rails flash and `303 See Other` redirects from controllers.
+## Settings and feedback
 
-Compact destructive actions should continue to declare
-`data: { turbo_confirm: "…" }` and use Turbo's native browser confirmation.
-When the user needs branded review UI or more context than one sentence,
-compose a dedicated native Nitro `Dialog` at the action's call site. The
-browser's top layer keeps that inline dialog clear of ancestor clipping and
-stacking contexts. Put record deletion on the edit route rather than adding a
-danger surface to every operational show page.
+Render `SettingsLayout` inside the normal shell. Settings destinations are
+links with `aria-current="page"`, not Buttons. Use `SettingsSection` only for
+distinct form regions; do not wrap every subsection in a Card or repeat the
+route title.
 
-## Baseline acceptance path
+Render `NitroKit::Toast::FlashMessages` once in the application layout. Keep
+ordinary Rails flash and `303 See Other` redirects. Use the dedicated
+[destructive action](destructive_action.md) and
+[flash](flash_and_toast.md) patterns for those flows.
 
-Before polishing empty-state illustration or dashboard summaries, verify:
+## Acceptance checklist
 
-- signup or sign-in selects the current membership and team;
-- another team cannot load the current team's records;
-- owner, administrator, and member policy differs where intended;
-- populated, empty, invalid, narrow, and destructive states work;
-- settings forms preserve validation and use one content gutter;
-- successful mutations redirect with `303` and invalid forms render with
-  `422`;
-- confirmation has both cancel and confirm coverage;
-- the shell, headings, tables, and forms remain usable without custom request
-  JavaScript.
+- Signup or sign-in selects a membership and team.
+- Cross-team records cannot be loaded.
+- Owner, administrator, and member policy differs where intended.
+- Populated, empty, invalid, narrow, settings, and destructive states work.
+- Successful mutations redirect with `303`; invalid forms render with `422`.