nitro_kit 2.0.0.alpha.3 → 2.0.0.alpha.4

data/docs/hotwire.md

@@ -1,106 +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.
+
+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.
 
 ## 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. For browser-sensitive interactions, follow
-[`browser_support.md`](browser_support.md); Nitro owns compatibility bridges for
-its own components.
-
-## Response matrix
-
-| 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.
-
-An HTML response branch preserves the request path when Turbo is unavailable;
-it is not a blanket guarantee that every surrounding component operates
-without JavaScript.
-
-## Forms and application Stimulus
-
-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. `data-turbo-confirm` is a Turbo
-enhancement, while an ordinary server-owned review route is the no-JavaScript
-confirmation path; neither an HTML response branch nor a form inside a closed
-dialog supplies that interaction by itself. See the canonical classifications
-in [`browser_support.md`](browser_support.md).
-
-Keep application controllers small, declarative, and disposable. For a
-self-submitting control, the complete controller can be:
-
-```js
-import { Controller } from "@hotwired/stimulus";
-
-export default class extends Controller {
-  submit() {
-    this.element.requestSubmit();
-  }
-}
-```
-
-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`.
-
-## Morphing and cache lifecycle
-
-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.
-
-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. `nk--dialog` closes an open Dialog, Sheet, or
-CommandPalette on `turbo:before-cache`; reconnecting does not install listeners
-or retain a mirrored open flag.
-
-## Frame escape and recovery
-
-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.
-
-Give lazy frames meaningful loading content. A failed frame should leave an
-understandable state and a path to retry or continue without JavaScript.
-
-## Verify behavior
+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.
+
+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.
+
+## Response contract
+
+| 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                            |
+
+Authentication and authorization failures are separate policy decisions; do
+not return `422` for them.
+
+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.
+
+## Stimulus and lifecycle
+
+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).
+
+Keep application controllers declarative. Prefer `data-action` over manually
+registered listeners. Release listeners, observers, timers, object URLs, and
+third-party instances in `disconnect`.
+
+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.
+
+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
 
 - 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,61 +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. Inventory user flows, every rendered
-   button treatment (including application-owned `.btn` classes and native Rails
-   helpers), joined controls, and the existing semantic color, focus, radius,
-   density, and typography tokens. Capture representative wide and narrow
-   screenshots before changing markup. 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. Preserve compound ownership: use `ButtonGroup`
-   for joined actions and `ControlGroup` for joined inputs, addons, and buttons
-   instead of rebuilding their geometry with a raw flex wrapper. Otherwise
-   preserve the control as application-owned Rails and semantic HTML; never
-   downgrade specialized behavior or retain copied Nitro Kit 1.x source as the
-   fallback. Preserve strict component boundaries: route native attributes
-   through `html:`, `aria:`, or `data:`, explicitly name icon-only Buttons and
-   triggers, and give custom `form.field` blocks explicit labels.
-9. Translate the application's existing semantic theme into documented public
-   `--nk-*` tokens. Preserve primary, focus, danger, neutral, font, density, and
-   radius decisions rather than selecting visually similar raw palette values.
-   Use `--nk-button-radius` when buttons intentionally have a different shape
-   from inputs and surfaces.
-10. Run `bin/rails nitro_kit:doctor`, fix actionable failures, and run the
-    application's relevant tests plus the generated upgrade smoke tests. When
-    the application uses strict i18n, render representative forms with
-    `ActiveModel::Translation.raise_on_missing_translations` enabled. Doctor
-    inventories migration work; a clean result is not runtime or visual
-    verification.
-11. Compare the same representative flows across the dated matrix in
-    `docs/browser_support.md`, including Mobile Safari where available, at wide
-    and narrow widths. Exercise keyboard focus and inspect computed styles for missing
-    application classes, stacked Button content, broken compound corners,
-    double focus rings, clipping, and theme drift. Re-audit rendered native
-    buttons, `button_tag`, `submit_tag`, and application-owned button classes
-    before declaring the migration complete.
+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,5 +1,8 @@
 # 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.
@@ -9,7 +12,7 @@ Treat a 1.x migration as a product-flow review, not a helper rename. Nitro Kit
 Add the 2.0 prerelease to the application's Gemfile:
 
 ```ruby
-gem "nitro_kit", "2.0.0.alpha.3"
+gem "nitro_kit", "2.0.0.alpha.4"
 ```
 
 Bundler records the exact released version in `Gemfile.lock`; commit `Gemfile`
@@ -30,7 +33,7 @@ rather than a moving Git branch.
 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. Inventory the existing semantic primary, focus, danger, neutral, font,
+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.
@@ -113,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
 
@@ -164,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
 
@@ -204,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
 
@@ -243,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:
@@ -282,15 +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 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. 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

data/docs/patterns/application_foundation.md

@@ -1,138 +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 `SettingsSection` 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, and set the document language on the root `html` element.
+- 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. At narrow widths, allow trailing actions to
-stack below the Back affordance and title so neither the title nor persistent
-actions are clipped.
-
-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 `SettingsSection` 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`.