plutonium 0.60.0 → 0.60.2

data/docs/superpowers/plans/2026-06-14-railless-portal.md

@@ -0,0 +1,761 @@
+# Railless Portal Support — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:subagent-driven-development (recommended) or superpowers-extended-cc:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a first-class "no rail" mode so a portal can omit the modern icon rail without inheriting its desktop layout offsets, resolvable globally (`config.shell = :plain`) and per-controller (`rail false`).
+
+**Architecture:** A single `rail?` predicate resolved through three tiers — global shell default → controller `rail` DSL (inherited) → layout delegates to the controller. `rail?` gates the sidebar partial, the initial-load `pu-rail-pinned` script, the `main` content offset, and a server-rendered `pu-no-rail` root class. `Topbar`/`StickyFooter` gain stable hook classes and a CSS rule keyed on `html.pu-no-rail` cancels their rail insets.
+
+**Tech Stack:** Ruby, Rails (7 / 8.0 / 8.1 via Appraisal), Phlex components, TailwindCSS 4 (esbuild via `yarn build`), Minitest.
+
+**User Verification:** NO — no user verification required.
+
+> **Commit policy:** The repo owner's standing rule is *do not stage or commit unless explicitly asked*. The `git commit` steps below are written for completeness; **skip them unless the user has explicitly authorized committing.** Run the verification (test) steps regardless.
+
+---
+
+## File Structure
+
+| File | Responsibility | Change |
+|------|----------------|--------|
+| `lib/plutonium/core/controller.rb` | Controller mixin; owns `rail` DSL + `rail?` resolution | Modify |
+| `lib/plutonium/ui/layout/resource_layout.rb` | Resource page layout; gates rail-dependent rendering | Modify |
+| `lib/plutonium/ui/layout/topbar.rb` | Fixed topbar; gains `pu-topbar` hook | Modify |
+| `lib/plutonium/ui/form/components/sticky_footer.rb` | Form action footer; gains `pu-sticky-footer` hook | Modify |
+| `src/css/components.css` | Source CSS; `html.pu-no-rail` inset cancel | Modify |
+| `app/assets/plutonium.css` / `.min.js` | Built assets | Regenerated by `yarn build` |
+| `lib/plutonium/auth/rodauth.rb` | Rodauth auth mixin; named `current_<account>` accessor | Modify |
+| `lib/plutonium/configuration.rb` | Config; doc `:plain` shell | Modify (comment) |
+| `lib/generators/pu/core/install/templates/config/initializers/plutonium.rb` | Install initializer; doc `:plain` | Modify (comment) |
+| `test/plutonium/core/controller_rail_test.rb` | Unit: `rail?` resolution + DSL | Create |
+| `test/plutonium/ui/layout/resource_layout_rail_test.rb` | Unit: `main_attributes` / `html_attributes` gating | Create |
+| `test/plutonium/ui/layout/topbar_test.rb` | Unit: `pu-topbar` hook | Modify |
+| `test/plutonium/ui/form/components/sticky_footer_test.rb` | Unit: `pu-sticky-footer` hook | Modify |
+| `test/integration/plain_shell_rendering_test.rb` | Integration: end-to-end `:plain` vs `:modern` | Create |
+| `test/plutonium/auth/rodauth_test.rb` | Unit: named accessor | Modify |
+| `docs/reference/...` + `.claude/skills/...` | Docs for `:plain` / `rail` / named accessor | Modify |
+
+---
+
+## Task 1: Controller `rail` DSL + `rail?` resolution
+
+**Goal:** Add an inherited `rail` class DSL and a `rail?` predicate to the controller mixin, defaulting from `config.shell`.
+
+**Files:**
+- Modify: `lib/plutonium/core/controller.rb`
+- Test: `test/plutonium/core/controller_rail_test.rb` (create)
+
+**Acceptance Criteria:**
+- [ ] `rail?` returns `true` when `config.shell == :modern`, `false` for `:plain` and `:classic`.
+- [ ] `rail true` / `rail false` override the shell default; `nil` (default) inherits it.
+- [ ] `_rail_enabled` is a `class_attribute` (inherits to subclasses; subclass can re-set).
+- [ ] `rail?` is registered as a helper method and is public (the layout calls `controller.rail?`).
+
+**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/core/controller_rail_test.rb` → all pass.
+
+**Steps:**
+
+- [ ] **Step 1: Write the failing test**
+
+Create `test/plutonium/core/controller_rail_test.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+
+class Plutonium::Core::ControllerRailTest < ActiveSupport::TestCase
+  def build_controller_class
+    Class.new(ActionController::Base) { include Plutonium::Core::Controller }
+  end
+
+  def with_shell(value)
+    original = Plutonium.configuration.shell
+    Plutonium.configuration.shell = value
+    yield
+  ensure
+    Plutonium.configuration.shell = original
+  end
+
+  test "rail? defaults to true for the modern shell" do
+    with_shell(:modern) do
+      assert build_controller_class.new.rail?
+    end
+  end
+
+  test "rail? defaults to false for the plain shell" do
+    with_shell(:plain) do
+      refute build_controller_class.new.rail?
+    end
+  end
+
+  test "rail? defaults to false for the classic shell" do
+    with_shell(:classic) do
+      refute build_controller_class.new.rail?
+    end
+  end
+
+  test "rail false overrides the modern default" do
+    klass = build_controller_class
+    klass.rail false
+    with_shell(:modern) do
+      refute klass.new.rail?
+    end
+  end
+
+  test "rail true overrides the plain default" do
+    klass = build_controller_class
+    klass.rail true
+    with_shell(:plain) do
+      assert klass.new.rail?
+    end
+  end
+
+  test "rail setting inherits to subclasses" do
+    parent = build_controller_class
+    parent.rail false
+    child = Class.new(parent)
+    with_shell(:modern) do
+      refute child.new.rail?
+    end
+  end
+
+  test "rail? is registered as a helper method" do
+    assert_includes build_controller_class._helper_methods, :rail?
+  end
+
+  test "rail? is callable as a public method" do
+    assert_respond_to build_controller_class.new, :rail?
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/core/controller_rail_test.rb`
+Expected: FAIL — `NoMethodError: undefined method 'rail'` / `rail?`.
+
+- [ ] **Step 3: Add the DSL and predicate**
+
+In `lib/plutonium/core/controller.rb`, inside the existing `included do` block (after `helper_method :registered_resources`, before the block closes at line 48), add:
+
+```ruby
+        class_attribute :_rail_enabled, instance_writer: false, default: nil
+        helper_method :rail?
+```
+
+Add a `class_methods do` block (place it just before the `private` keyword on line 50):
+
+```ruby
+      class_methods do
+        # Enable or disable the modern icon rail for this controller and its
+        # subclasses. nil (the default) inherits the global shell default.
+        def rail(enabled)
+          self._rail_enabled = enabled
+        end
+      end
+
+      # Whether the modern icon rail is active for this request. Resolves the
+      # per-controller `rail` setting, falling back to the shell default.
+      # Public: the resource layout calls `controller.rail?`.
+      def rail?
+        return _rail_enabled unless _rail_enabled.nil?
+        Plutonium.configuration.shell == :modern
+      end
+```
+
+> Note: `rail?` is defined *above* the `private` keyword so it stays public.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/core/controller_rail_test.rb`
+Expected: PASS (8 tests).
+
+- [ ] **Step 5: Commit** *(only if commits are authorized — see Commit policy)*
+
+```bash
+git add lib/plutonium/core/controller.rb test/plutonium/core/controller_rail_test.rb
+git commit -m "feat(layout): add controller rail DSL and rail? predicate"
+```
+
+---
+
+## Task 2: Gate `ResourceLayout` rendering on `rail?`
+
+**Goal:** Make `ResourceLayout` delegate `rail?` to the controller and skip every rail-dependent output (sidebar partial, initial pin script, `main` offset) when rail-less, emitting `pu-no-rail` on `<html>`.
+
+**Files:**
+- Modify: `lib/plutonium/ui/layout/resource_layout.rb`
+- Test: `test/plutonium/ui/layout/resource_layout_rail_test.rb` (create)
+
+**Acceptance Criteria:**
+- [ ] `rail?` delegates to `controller.rail?`.
+- [ ] `render_before_main` renders `resource_sidebar` only when `rail?`.
+- [ ] `render_pre_paint_scripts` adds the `pu-rail-pinned` initial script only when `rail?`.
+- [ ] `main_attributes` includes `lg:pl-20` only for modern+rail; `:plain` and modern-without-rail get no rail offset; `:classic` keeps `pt-20 lg:ml-64`.
+- [ ] `html_attributes` adds class `pu-no-rail` when `!rail?` and shell is not `:classic`; otherwise unchanged.
+
+**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/resource_layout_rail_test.rb` → all pass.
+
+**Steps:**
+
+- [ ] **Step 1: Write the failing test**
+
+Create `test/plutonium/ui/layout/resource_layout_rail_test.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+
+class Plutonium::UI::Layout::ResourceLayoutRailTest < ActiveSupport::TestCase
+  def build_layout(rail:)
+    layout = Plutonium::UI::Layout::ResourceLayout.allocate
+    layout.define_singleton_method(:rail?) { rail }
+    layout
+  end
+
+  def with_shell(value)
+    original = Plutonium.configuration.shell
+    Plutonium.configuration.shell = value
+    yield
+  ensure
+    Plutonium.configuration.shell = original
+  end
+
+  test "main_attributes includes lg:pl-20 for modern with rail" do
+    with_shell(:modern) do
+      classes = build_layout(rail: true).send(:main_attributes)[:class]
+      assert_includes classes, "lg:pl-20"
+    end
+  end
+
+  test "main_attributes drops the rail offset for modern without rail" do
+    with_shell(:modern) do
+      classes = build_layout(rail: false).send(:main_attributes)[:class]
+      refute_includes classes, "lg:pl-20"
+    end
+  end
+
+  test "main_attributes has no rail offset for the plain shell" do
+    with_shell(:plain) do
+      classes = build_layout(rail: false).send(:main_attributes)[:class]
+      refute_includes classes, "lg:pl-20"
+      refute_includes classes, "lg:ml-64"
+    end
+  end
+
+  test "main_attributes keeps the classic sidebar offset" do
+    with_shell(:classic) do
+      classes = build_layout(rail: false).send(:main_attributes)[:class]
+      assert_includes classes, "lg:ml-64"
+    end
+  end
+
+  test "html_attributes adds pu-no-rail when rail-less (plain)" do
+    with_shell(:plain) do
+      attrs = build_layout(rail: false).send(:html_attributes)
+      assert_includes attrs[:class].to_s, "pu-no-rail"
+    end
+  end
+
+  test "html_attributes has no pu-no-rail when rail present" do
+    with_shell(:modern) do
+      attrs = build_layout(rail: true).send(:html_attributes)
+      refute_includes attrs[:class].to_s, "pu-no-rail"
+    end
+  end
+
+  test "html_attributes leaves classic shell untouched" do
+    with_shell(:classic) do
+      attrs = build_layout(rail: false).send(:html_attributes)
+      refute_includes attrs[:class].to_s, "pu-no-rail"
+    end
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/resource_layout_rail_test.rb`
+Expected: FAIL — `main_attributes` lacks the plain branch / no `html_attributes` override (no `pu-no-rail`).
+
+- [ ] **Step 3: Update `ResourceLayout`**
+
+Replace the body of `lib/plutonium/ui/layout/resource_layout.rb` (the `private` section) with:
+
+```ruby
+      class ResourceLayout < Base
+        private
+
+        # Whether the modern icon rail is active for this request. Delegates to
+        # the controller's resolution (shell default + per-controller `rail`).
+        def rail? = controller.rail?
+
+        # Sets pu-rail-pinned immediately on initial page load so the rail
+        # renders in its pinned state from the first frame. Turbo navigations
+        # are handled by the turbo:before-render listener in Base. Skipped
+        # entirely when the layout renders no rail.
+        def render_pre_paint_scripts
+          super
+          return unless rail?
+
+          script do
+            raw(safe(<<~JS))
+              (function () {
+                try {
+                  if (localStorage.getItem("pu_rail_pinned") !== "false") {
+                    document.documentElement.classList.add("pu-rail-pinned");
+                  }
+                } catch (e) {}
+              })();
+            JS
+          end
+        end
+
+        # Adds `pu-no-rail` to <html> (server-side, no FOUC) so decoupled fixed
+        # chrome (Topbar, form StickyFooter) can cancel their rail insets.
+        # Scoped to the modern family — :classic keeps its own offsets.
+        def html_attributes
+          attrs = super
+          return attrs if Plutonium.configuration.shell == :classic
+
+          rail? ? attrs : mix(attrs, {class: "pu-no-rail"})
+        end
+
+        def main_attributes
+          classes = case Plutonium.configuration.shell
+          when :modern
+            rail? ? "pt-16 pb-6 px-6 lg:pl-20" : "pt-16 pb-6 px-6"
+          when :plain
+            "pt-16 pb-6 px-6"
+          else # :classic
+            "pt-20 lg:ml-64"
+          end
+
+          mix(super, {class: classes})
+        end
+
+        def page_title
+          make_page_title(
+            controller.instance_variable_get(:@page_title)
+          )
+        end
+
+        def render_before_main
+          super
+
+          render partial("resource_header")
+          render partial("resource_sidebar") if rail?
+        end
+      end
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/resource_layout_rail_test.rb`
+Expected: PASS (7 tests).
+
+- [ ] **Step 5: Commit** *(only if authorized)*
+
+```bash
+git add lib/plutonium/ui/layout/resource_layout.rb test/plutonium/ui/layout/resource_layout_rail_test.rb
+git commit -m "feat(layout): gate rail rendering and offsets on rail?"
+```
+
+---
+
+## Task 3: Stable hook classes + `pu-no-rail` CSS + asset build
+
+**Goal:** Give `Topbar` and `StickyFooter` stable classes and add a CSS rule that cancels their `lg:left-14` rail inset under `html.pu-no-rail`; rebuild assets.
+
+**Files:**
+- Modify: `lib/plutonium/ui/layout/topbar.rb` (line 36 nav class)
+- Modify: `lib/plutonium/ui/form/components/sticky_footer.rb` (line 9 div class)
+- Modify: `src/css/components.css` (after the `html.pu-rail-pinned main` rule, ~line 758)
+- Modify (regenerated): `app/assets/plutonium.css`, `app/assets/plutonium.min.js` via `yarn build`
+- Test: `test/plutonium/ui/layout/topbar_test.rb`, `test/plutonium/ui/form/components/sticky_footer_test.rb`
+
+**Acceptance Criteria:**
+- [ ] `Topbar` nav class contains `pu-topbar` (and still `lg:left-14`).
+- [ ] `StickyFooter` div class contains `pu-sticky-footer` (and still `lg:left-14`).
+- [ ] `src/css/components.css` cancels the inset to `left: 0` for both under `html.pu-no-rail` at `min-width: 1024px`.
+- [ ] `app/assets/plutonium.css` rebuilt and contains `pu-no-rail`.
+
+**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/topbar_test.rb test/plutonium/ui/form/components/sticky_footer_test.rb` → pass; `grep -c "pu-no-rail" app/assets/plutonium.css` → ≥ 1.
+
+**Steps:**
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/plutonium/ui/layout/topbar_test.rb` (before the final `end`):
+
+```ruby
+  test "nav has pu-topbar stable hook class" do
+    html = render_html(build_component)
+    assert_includes html, "pu-topbar"
+  end
+```
+
+Append to `test/plutonium/ui/form/components/sticky_footer_test.rb` (before the final `end`):
+
+```ruby
+  def test_outer_div_has_pu_sticky_footer_stable_hook
+    outer_class = capture_outer_div_class
+    assert_includes outer_class, "pu-sticky-footer"
+  end
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/topbar_test.rb test/plutonium/ui/form/components/sticky_footer_test.rb`
+Expected: FAIL — `pu-topbar` / `pu-sticky-footer` not present.
+
+- [ ] **Step 3: Add the hook classes**
+
+In `lib/plutonium/ui/layout/topbar.rb`, change the `nav` class string (line 36) from:
+
+```ruby
+            class: "fixed top-0 right-0 left-0 lg:left-14 z-30 h-12 " \
+```
+to:
+```ruby
+            class: "pu-topbar fixed top-0 right-0 left-0 lg:left-14 z-30 h-12 " \
+```
+
+In `lib/plutonium/ui/form/components/sticky_footer.rb`, change the `div` class (line 9) from:
+
+```ruby
+            div(class: "fixed bottom-0 left-0 right-0 lg:left-14 z-20 " \
+```
+to:
+```ruby
+            div(class: "pu-sticky-footer fixed bottom-0 left-0 right-0 lg:left-14 z-20 " \
+```
+
+- [ ] **Step 4: Add the CSS rule**
+
+In `src/css/components.css`, immediately after the existing block:
+
+```css
+@media (min-width: 1024px) {
+  html.pu-rail-pinned main {
+    padding-left: 15.5rem !important;
+  }
+}
+```
+
+add:
+
+```css
+/* Rail-less layouts (html.pu-no-rail): cancel the icon-rail inset on fixed
+   chrome so the topbar and form sticky footer span the full width. */
+@media (min-width: 1024px) {
+  html.pu-no-rail .pu-topbar,
+  html.pu-no-rail .pu-sticky-footer {
+    left: 0 !important;
+  }
+}
+```
+
+- [ ] **Step 5: Rebuild assets**
+
+Run: `yarn build`
+Expected: rebuilds `app/assets/plutonium.css` and `app/assets/plutonium.min.js`.
+
+- [ ] **Step 6: Verify tests and built asset**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/ui/layout/topbar_test.rb test/plutonium/ui/form/components/sticky_footer_test.rb`
+Expected: PASS.
+Run: `grep -c "pu-no-rail" app/assets/plutonium.css`
+Expected: ≥ 1.
+
+- [ ] **Step 7: Commit** *(only if authorized)*
+
+```bash
+git add lib/plutonium/ui/layout/topbar.rb lib/plutonium/ui/form/components/sticky_footer.rb src/css/components.css app/assets/plutonium.css app/assets/plutonium.min.js test/plutonium/ui/layout/topbar_test.rb test/plutonium/ui/form/components/sticky_footer_test.rb
+git commit -m "feat(layout): add pu-topbar/pu-sticky-footer hooks and pu-no-rail inset cancel"
+```
+
+---
+
+## Task 4: End-to-end integration test (`:plain` vs `:modern`)
+
+**Goal:** Prove a rail-less render omits the icon rail and pin script and carries `pu-no-rail`, while modern is unchanged.
+
+**Files:**
+- Test: `test/integration/plain_shell_rendering_test.rb` (create)
+
+**Acceptance Criteria:**
+- [ ] With `config.shell = :plain`: response has no `icon-rail` controller, no `classList.add("pu-rail-pinned")`, and `<html ... class="...pu-no-rail...">`.
+- [ ] With `config.shell = :modern`: response includes `icon-rail` and the pin script.
+- [ ] Shell config is restored in teardown.
+
+**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/integration/plain_shell_rendering_test.rb` → all pass.
+
+**Steps:**
+
+- [ ] **Step 1: Write the integration test**
+
+Create `test/integration/plain_shell_rendering_test.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+
+class PlainShellRenderingTest < ActionDispatch::IntegrationTest
+  include IntegrationTestHelper
+
+  setup do
+    @admin = create_admin!
+    login_as_admin(@admin)
+    @original_shell = Plutonium.configuration.shell
+  end
+
+  teardown do
+    Plutonium.configuration.shell = @original_shell
+  end
+
+  test "plain shell renders rail-less" do
+    Plutonium.configuration.shell = :plain
+    get "/admin/kitchen_sinks"
+
+    assert_response :success
+    # NOTE: probe rail-gated-specific markers, not bare "icon-rail" /
+    # 'classList.add("pu-rail-pinned")' — those also appear in the
+    # always-present turbo:before-render listener in Base#render_pre_paint_scripts.
+    refute_includes response.body, 'data-controller="sidebar icon-rail"',
+      "plain shell should not render the icon rail"
+    refute_includes response.body, 'if (localStorage.getItem("pu_rail_pinned") !== "false") {',
+      "plain shell should not emit the initial pin script (Base listener's variant is prefixed `hasRail &&`)"
+    assert_match(/<html[^>]*class="[^"]*pu-no-rail/, response.body,
+      "plain shell should mark <html> with pu-no-rail")
+  end
+
+  test "modern shell still renders the icon rail and pin script" do
+    Plutonium.configuration.shell = :modern
+    get "/admin/kitchen_sinks"
+
+    assert_response :success
+    assert_includes response.body, 'data-controller="sidebar icon-rail"'
+    assert_includes response.body, 'if (localStorage.getItem("pu_rail_pinned") !== "false") {'
+    refute_match(/<html[^>]*class="[^"]*pu-no-rail/, response.body)
+  end
+end
+```
+
+- [ ] **Step 2: Run the test**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/integration/plain_shell_rendering_test.rb`
+Expected: PASS (2 tests). If FAIL, the gating in Tasks 1–2 is incomplete — fix there, not here.
+
+- [ ] **Step 3: Commit** *(only if authorized)*
+
+```bash
+git add test/integration/plain_shell_rendering_test.rb
+git commit -m "test(layout): integration coverage for plain (rail-less) shell"
+```
+
+---
+
+## Task 5: Named `current_<account>` Rodauth accessor
+
+**Goal:** `Plutonium::Auth::Rodauth(name)` exposes `current_<name>` (aliased to `current_user`) in addition to `current_user`, both as helper methods.
+
+**Files:**
+- Modify: `lib/plutonium/auth/rodauth.rb`
+- Test: `test/plutonium/auth/rodauth_test.rb`
+
+**Acceptance Criteria:**
+- [ ] `Rodauth.for(:admin)` registers both `:current_user` and `:current_admin` as helper methods.
+- [ ] `current_admin` returns the same value as `current_user` (`rodauth.rails_account`).
+- [ ] `Rodauth.for(:user)` still works (no duplicate-name breakage).
+
+**Verify:** `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/auth/rodauth_test.rb` → all pass.
+
+**Steps:**
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/plutonium/auth/rodauth_test.rb` (before the `private` keyword):
+
+```ruby
+  test "module includes named current_<account> helper method" do
+    mod = Plutonium::Auth::Rodauth.for(:admin)
+    controller_class = build_controller_class(mod)
+
+    assert_includes controller_class._helper_methods, :current_admin
+  end
+
+  test "named accessor returns the same account as current_user" do
+    mod = Plutonium::Auth::Rodauth.for(:admin)
+    controller_class = build_controller_class(mod)
+    controller = controller_class.new
+
+    assert_equal controller.send(:current_user), controller.send(:current_admin)
+  end
+
+  test "for(:user) still defines current_user without error" do
+    mod = Plutonium::Auth::Rodauth.for(:user)
+    controller_class = build_controller_class(mod)
+
+    assert_includes controller_class._helper_methods, :current_user
+  end
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/auth/rodauth_test.rb`
+Expected: FAIL — `current_admin` not a helper method.
+
+- [ ] **Step 3: Add the named accessor**
+
+In `lib/plutonium/auth/rodauth.rb`, update the heredoc. Change the `included do` helper registration from:
+
+```ruby
+          included do
+            helper_method :current_user
+            helper_method :logout_url
+            helper_method :profile_url
+          end
+```
+to:
+```ruby
+          included do
+            helper_method :current_user, :current_#{name}
+            helper_method :logout_url
+            helper_method :profile_url
+          end
+```
+
+And after the `current_user` definition:
+
+```ruby
+          def current_user
+            rodauth.rails_account
+          end
+```
+add:
+```ruby
+          alias_method :current_#{name}, :current_user
+```
+
+> When `name == :user`, `current_#{name}` is just `current_user` — the alias and the duplicate `helper_method` arg are harmless no-ops.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bundle exec appraisal rails-8.1 ruby -Itest test/plutonium/auth/rodauth_test.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit** *(only if authorized)*
+
+```bash
+git add lib/plutonium/auth/rodauth.rb test/plutonium/auth/rodauth_test.rb
+git commit -m "feat(auth): expose named current_<account> accessor on Rodauth(name)"
+```
+
+---
+
+## Task 6: Documentation + config comments
+
+**Goal:** Document the `:plain` shell, the controller `rail` DSL, and the named Rodauth accessor; add explanatory comments where `shell` is configured.
+
+**Files:**
+- Modify: `lib/plutonium/configuration.rb` (the `shell` attr comment, ~line 30)
+- Modify: `lib/generators/pu/core/install/templates/config/initializers/plutonium.rb` (~line 6)
+- Modify: relevant docs in `docs/` and skills in `.claude/skills/` (UI/app shell docs; auth docs)
+
+**Acceptance Criteria:**
+- [ ] `configuration.rb` documents `:plain` alongside `:modern`/`:classic`.
+- [ ] Install initializer notes the `:plain` option in a comment.
+- [ ] Docs/skills explain: `config.shell = :plain`, per-controller `rail false`/`true` (incl. the one-line portal-concern example), and the named `current_<account>` accessor.
+- [ ] `grep -ri "rail false" docs .claude/skills` returns at least one hit.
+
+**Verify:** `yarn docs:build` → no broken links; `grep -rl "config.shell = :plain" docs .claude/skills` → ≥ 1.
+
+**Steps:**
+
+- [ ] **Step 1: Update the configuration comment**
+
+In `lib/plutonium/configuration.rb`, change the `shell` doc comment (line 30) from:
+
+```ruby
+    # @return [Symbol] :classic (legacy Header/Sidebar) or :modern (Topbar/IconRail)
+    attr_accessor :shell
+```
+to:
+```ruby
+    # @return [Symbol] :modern (Topbar/IconRail, default), :plain (Topbar, no
+    #   icon rail), or :classic (legacy Header/Sidebar).
+    attr_accessor :shell
+```
+
+- [ ] **Step 2: Update the install initializer comment**
+
+In `lib/generators/pu/core/install/templates/config/initializers/plutonium.rb`, add a comment above `config.shell = :modern`:
+
+```ruby
+  # Shell variant: :modern (icon rail), :plain (no rail), or :classic (legacy).
+  config.shell = :modern
+```
+
+- [ ] **Step 3: Update docs and skills**
+
+Add a "Shell variants & the icon rail" subsection to the appropriate UI/app shell doc under `docs/` (follow the existing doc structure) covering:
+- `config.shell = :plain` for an app-wide rail-less shell.
+- Per-controller / per-portal override:
+  ```ruby
+  module CustomerPortal
+    module Concerns
+      module Controller
+        extend ActiveSupport::Concern
+        included { rail false }  # entire portal rail-less
+      end
+    end
+  end
+  ```
+- Stable hooks `pu-topbar` / `pu-sticky-footer` and the `html.pu-no-rail` body class for custom CSS.
+
+Update the `plutonium-ui` (and/or `plutonium-app`) skill in `.claude/skills/` with the same `rail`/`:plain` guidance, and the `plutonium-auth` skill with the named `current_<account>` accessor.
+
+- [ ] **Step 4: Verify docs build and grep**
+
+Run: `yarn docs:build`
+Expected: builds with no broken-link errors.
+Run: `grep -rl "config.shell = :plain" docs .claude/skills`
+Expected: ≥ 1 file.
+
+- [ ] **Step 5: Commit** *(only if authorized)*
+
+```bash
+git add lib/plutonium/configuration.rb lib/generators/pu/core/install/templates/config/initializers/plutonium.rb docs .claude/skills
+git commit -m "docs(layout): document :plain shell, rail DSL, and named auth accessor"
+```
+
+---
+
+## Final verification
+
+- [ ] Run the full affected suite on the default Rails version:
+
+```bash
+bundle exec appraisal rails-8.1 ruby -Itest \
+  test/plutonium/core/controller_rail_test.rb \
+  test/plutonium/ui/layout/resource_layout_rail_test.rb \
+  test/plutonium/ui/layout/topbar_test.rb \
+  test/plutonium/ui/form/components/sticky_footer_test.rb \
+  test/integration/plain_shell_rendering_test.rb \
+  test/plutonium/auth/rodauth_test.rb
+```
+Expected: all green.
+
+- [ ] Run the whole suite across versions to catch regressions:
+
+```bash
+bundle exec appraisal rake test
+```
+Expected: no new failures versus baseline.
+
+- [ ] Confirm `app/assets/plutonium.css` was rebuilt (`yarn build`) and contains `pu-no-rail`.
+```