nitro_kit 0.9.0 → 2.0.0.alpha.2

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.2"
+```
+
+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,22 @@
+# 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. Nitro Kit's starter therefore remains a thin one-command entry point:
+
+```sh
+rails new my_app -m https://nitrokit.dev/template.rb
+```
+
+The template adds Nitro Kit and invokes `nitro_kit:install`. The generator owns
+the project-local skills and `AGENTS.md`. The template does not copy Nitro
+components, controllers, authentication, teams, billing, or product models.
+
+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.

data/docs/patterns/application_foundation.md

@@ -0,0 +1,136 @@
+# A durable 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.
+
+## 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.
+
+## 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.
+
+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.
+
+## Keep settings plain
+
+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.
+
+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.
+
+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.
+
+## Centralize cross-cutting feedback
+
+Render `Toast::FlashMessages` once in the application layout. Keep using
+ordinary Rails flash and `303 See Other` redirects from controllers.
+
+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.
+
+## Baseline acceptance path
+
+Before polishing empty-state illustration or dashboard summaries, verify:
+
+- 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.

data/docs/patterns/crud_resource.md

@@ -0,0 +1,144 @@
+# A complete product resource
+
+Build CRUD as one coherent product surface, not independent generated screens.
+Before writing the views, name the resource, tenant boundary, actor, lifecycle,
+visibility rules, and states. Implement index, form, detail, destructive action,
+and their tests together.
+
+## Summary
+
+- Build index, form, detail, destructive action, and their tests as one
+  surface; name the resource, tenant boundary, actor, lifecycle, and states
+  before writing views.
+- `AppShell(layout: :hybrid)` frames the admin area, and a `Toolbar` in
+  `shell.topbar` carries the route's single `h1` plus its basic actions.
+- Spend hierarchy once: one route, one `h1`, an `h2` only for a genuinely
+  separate region, and no resource name repeated across toolbar, `PageHeader`,
+  `DataSection`, Card, and caption.
+- Child routes add one compact icon Back link before the title instead of a
+  trailing Cancel action.
+- One responsive padding rule on the main wrapper owns the page gutter;
+  data-heavy hybrid CRUD content uses the full available width.
+
+## Use the hybrid application frame
+
+An authenticated admin area defaults to `AppShell(layout: :hybrid)`. Nitro Kit
+owns the desktop sidebar, mobile menu button, navigation dialog, focus behavior,
+and responsive transition. The application provides destinations and current
+state.
+
+Put a `Toolbar` in `shell.topbar`. Its leading region contains the route's one
+`h1`; its trailing region contains basic actions such as New, Edit, Cancel,
+Save, Publish, or View. A Button outside a form can submit it through the
+native `form:` attribute. This keeps the same action hierarchy on narrow and
+wide screens without custom JavaScript.
+
+```ruby
+AppShell(id: "admin", layout: :hybrid) do |shell|
+  shell.navigation { render admin_navigation }
+  shell.topbar do
+    Toolbar do |toolbar|
+      toolbar.leading { h1 { page_title } }
+      toolbar.trailing do
+        Button(
+          "Save",
+          type: :submit,
+          form: dom_id(@post, :form),
+          variant: :primary
+        )
+      end
+    end
+  end
+  shell.main do
+    div(data: { ui: "admin-main" }) do
+      render page
+    end
+  end
+end
+```
+
+Child routes add one compact Back link before the title. Prefer an icon-only
+Button with an explicit label such as `aria: { label: "Back to projects" }`.
+Do not repeat that navigation as a trailing Cancel action.
+
+The application stylesheet gives `admin-main` one responsive padding rule.
+Child pages do not add another outer gutter. Keep data-heavy hybrid CRUD
+content full width; constrain only a specific content-led region whose measure
+benefits from it.
+
+Do not add viewport height or another outer padding rule to `admin-main`; the
+shell owns viewport geometry and the wrapper owns the one page gutter. Use the
+same shell and gutter on team administration and settings routes.
+Place a bottom-anchored Settings destination after `AppNavigation#spacer`, then
+compose settings subsections with `SettingsLayout` and plain `FormSection`
+regions. Settings destinations are links with `aria-current`, not action
+Buttons. Read `application_foundation.md` for the complete application frame.
+
+## Spend hierarchy once
+
+- One route, one `h1`, normally in the shell toolbar.
+- Add an `h2` only for a genuinely separate region.
+- Do not repeat “Posts” in the toolbar, `PageHeader`, `DataSection`, Card, and
+  visible table caption.
+- Use `PageHeader` for a content-led introduction, not as mandatory CRUD
+  ceremony under an existing toolbar.
+- Prefer whitespace and dividers. Use Card only for a bounded object that
+  benefits from its own surface. Never default to Card inside Card.
+
+An index begins with a short introduction only if it adds useful context, then
+renders its table and pagination directly. Use `DataSection` when a page has
+multiple independently named datasets. At zero records, replace the data region
+with one intentional `EmptyState`; keep the primary New action in the toolbar.
+
+A new or edit page begins with `FormSection`. Use one form component for new,
+edit, and invalid renders. Put the primary submit in the toolbar by setting the
+button's `form:` to the form's stable DOM ID. Invalid submissions render the
+same model and form with `422 Unprocessable Entity`. The toolbar owns that
+action: do not render a second Save or Create submit inside the form body.
+
+A detail page begins with status or stable metadata, then the resource itself.
+Keep status inside that normal details flow instead of detaching it into a
+second side panel.
+Use the authenticated `show` route as the operational detail or draft preview.
+Put lifecycle forms in the page and associate their toolbar buttons with
+`form:`. Put destructive confirmation in one separate `DangerZone` on edit,
+with a safe escape back to the record. Do not make every show page end in a
+large deletion surface.
+
+## Model and route the lifecycle
+
+Scope every lookup through `Current.team` or `Current.account`. Record
+`Current.user` as author, creator, or publisher. If a state has provenance,
+timing, or behavior, model it as a record and expose it as a noun resource:
+
+```ruby
+namespace :admin do
+  resources :posts do
+    resource :publication,
+      only: %i[create destroy],
+      module: :posts
+  end
+end
+```
+
+The main controller keeps the seven REST actions. Successful mutations redirect
+with `303 See Other`. Publication create and destroy invoke domain methods and
+redirect. Public controllers query published records only. Ordinary Rails forms
+and Turbo Drive are the default; do not add fetch code for CRUD submissions.
+
+## Ship the acceptance path
+
+Request tests cover tenant isolation, public visibility, successful `303`
+redirects, invalid `422` renders, pagination, and lifecycle resources. Rendering
+assertions should also protect the high-level composition: hybrid AppShell,
+one `h1`, navigation, toolbar action, actual form association, table or empty
+state, and destructive confirmation. Add one browser test for the meaningful
+end-to-end path, using Capybara waiting assertions instead of sleeps.
+
+Assert that each primary action has one visible control. A toolbar-associated
+form submit plus an identical body submit is duplication, even when both invoke
+the same valid form.
+
+Before finishing, inspect a populated index, empty index, invalid form, narrow
+form, draft detail, published detail, and edit-owned destructive dialog. Remove any extra
+heading, surface, wrapper, or page gutter that does not communicate information.