plutonium 0.62.2 → 0.63.0

data/docs/guides/custom-actions.md

@@ -11,7 +11,7 @@ A button appears in the right place (show page / table row / index header / bulk
 | Flavor | Use for |
 |---|---|
 | **Simple action** — navigate to a URL | Linking to external docs, jumping to a custom page that does its own thing |
-| **Interactive action** — run an interaction class | Anything with business logic (the common case) |
+| **Interactive action** — run an interaction class | Anything that *does* something (the common case) |
 
 Prefer interactive actions. They handle authorization, form rendering, modal chrome, success/failure messaging, and automatic redirects — all for free.
 
@@ -20,7 +20,16 @@ Prefer interactive actions. They handle authorization, form rendering, modal chr
 ### 1. Write the interaction
 
 ```ruby
-# app/interactions/publish_post_interaction.rb
+# app/models/post.rb — what publishing actually means
+class Post < ApplicationRecord
+  def publish!(on: Time.current)
+    update!(published: true, published_at: on)
+  end
+end
+```
+
+```ruby
+# app/interactions/publish_post_interaction.rb — the button in front of it
 class PublishPostInteraction < ResourceInteraction
   presents label: "Publish",
            icon:  Phlex::TablerIcons::Send,
@@ -29,7 +38,7 @@ class PublishPostInteraction < ResourceInteraction
   attribute :resource
 
   def execute
-    resource.update!(published: true, published_at: Time.current)
+    resource.publish!
     succeed(resource).with_message("Post published!")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -41,6 +50,10 @@ end
 Plutonium doesn't rescue it automatically. Always rescue when using `create!` / `update!` / `save!`, return `failed(e.record.errors)`.
 :::
 
+::: tip Why `publish!` is on the model
+An interaction can only be built with a `view_context` — it's a presentation object. A two-line `update!` inline in `execute` is fine while the button is the only caller; the moment a scheduled-publishing job wants the same behaviour it has to duplicate it or fake a view context. Full rule: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
+:::
+
 ### 2. Register it in the definition
 
 ```ruby
@@ -106,7 +119,7 @@ class Company::InviteUserInteraction < ResourceInteraction
   validates :role,  presence: true
 
   def execute
-    UserInvite.create!(company: resource, email: email, role: role)
+    resource.invite!(email: email, role: role, by: current_user)
     succeed(resource).with_message("Invitation sent to #{email}.")
   rescue ActiveRecord::RecordInvalid => e
     failed(e.record.errors)
@@ -114,6 +127,8 @@ class Company::InviteUserInteraction < ResourceInteraction
 end
 ```
 
+`Company#invite!` creates the row *and* sends the mail. Both are things a seat-provisioning job needs to do without a browser anywhere in sight — see the [full worked example](/reference/behavior/interactions#complete-example).
+
 ## Bulk actions
 
 Plural `attribute :resources` automatically becomes a bulk action. The table gets checkboxes and a bulk-actions toolbar.
@@ -146,6 +161,36 @@ Two related behaviors:
 
 ![Bulk action toolbar with selected drafts](/images/guides/custom-actions-bulk.png)
 
+## When the work is too slow for a request
+
+The bulk action above updates every selected record inside the request. That is fine for a screenful; it is not fine for a few thousand, or for anything that calls a slow third party. Swap `execute` for `async`, and the same interaction dispatches the work to a background run instead:
+
+```ruby
+class BulkArchiveInteraction < ResourceInteraction
+  presents label: "Archive Selected", icon: Phlex::TablerIcons::Archive
+
+  attribute :resources
+  attribute :reason, :string
+
+  async do
+    on_failure :continue          # :halt (default) | :continue | :transactional
+    def perform_on(record)
+      record.archive!(reason: options["reason"])
+    end
+  end
+end
+```
+
+Nothing else about the action changes — the definition, the policy method and the form are the same. Only the work moves.
+
+Three things worth knowing:
+
+- **The block is the run's class body, not `execute`.** The work runs later, in a job with no controller, so it cannot close over anything in the interaction. Its inputs arrive through `options`.
+- **The user is sent back where they were**, and the index they land on shows a banner for the run with a link to its progress page.
+- **Permissions are re-checked per record, at perform time** — not replayed from dispatch. A permission revoked while the run is working stops applying to the rest of it.
+
+Full detail, including file attributes, failure policies and resuming a crashed run: [Async Interactions](/reference/behavior/async-interactions).
+
 ## Resource action (no specific record)
 
 Neither `:resource` nor `:resources` → resource action on the index page:
@@ -187,7 +232,11 @@ action :name,
   # Behavior
   confirmation: "Are you sure?",
   modal: :slideover,                     # :slideover / :centered — overrides definition's modal mode
-  size:  :lg                             # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
+  size:  :lg,                            # :sm / :md / :lg / :xl / :auto / :full — overrides definition's modal size
+
+  # HTML attributes — author wins over the framework's on every key
+  link:   {target: "_blank", rel: "noopener"},  # every <a> rendering (toolbar GET link, dropdown items, bulk links, card show link)
+  button: {data: {analytics: "archive"}}        # the button_to <form> wrapper (non-GET toolbar rendering)
 ```
 
 Full options: [Reference › Resource › Actions › Action options](/reference/resource/actions#action-options).
@@ -201,7 +250,8 @@ action :documentation,
   label: "Docs",
   route_options: {url: "https://docs.example.com"},
   icon: Phlex::TablerIcons::Book,
-  resource_action: true
+  resource_action: true,
+  link: {target: "_blank", rel: "noopener noreferrer"}   # open in a new tab
 
 action :reports,
   route_options: {action: :reports},   # links to PostsController#reports
@@ -231,18 +281,28 @@ end
 
 Every resource gets `:archive` automatically.
 
-## Chaining interactions
+## Where the logic goes
+
+Interactions are presentation objects — they need a `view_context` to exist at all. So the reflex to reach for when an operation grows:
 
 ```ruby
+# 🚫 Three interactions, three view contexts, none of it callable from a job
+CreateUserInteraction.call(view_context:, **user_params)
+  .and_then { |user| SendWelcomeEmail.call(view_context:, user:) }
+  .and_then { |user| LogActivity.call(view_context:, user:) }
+```
+
+```ruby
+# ✅ One model method; the interaction just presents it
 def execute
-  CreateUserInteraction.call(view_context:, **user_params)
-    .and_then { |r| SendWelcomeEmail.call(view_context:, user: r.value) }
-    .and_then { |r| LogActivity.call(view_context:, user: r.value) }
-    .with_message("User created and welcomed!")
+  user = User.register!(**attributes)   # welcome email + audit row live in here
+  succeed(user).with_message("Welcome aboard!")
 end
 ```
 
-The chain short-circuits on the first failure.
+Sending a welcome email and writing an audit row are exactly what a signup API endpoint or a rake task also does — and neither has a view context to hand.
+
+The rule isn't "never put logic in an interaction". A single-caller operation can stay inline in `execute`; don't pre-extract. **The second caller is the trigger** — and the destination is the model, Rails-style, not a new service layer. Chaining three interactions is usually the tell that you already crossed it. Full explanation: [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for).
 
 ## Common issues
 
@@ -250,10 +310,12 @@ The chain short-circuits on the first failure.
 - **`ActiveRecord::RecordInvalid` crashes the action** — not rescued automatically. Wrap with `rescue`, return `failed(e.record.errors)`.
 - **Bulk action fails on some records** — that's by design. Bulk policy is checked per-record; if any fails, the whole request is rejected. Either fix authorization or pre-filter the selection.
 - **Confirmation prompt shows when you don't want one** — pass `confirmation: false` on the action.
+- **The action times out on a large selection** — the work is running inside the request. Move it to a background run with `async`, above.
 
 ## Related
 
 - [Reference › Resource › Actions](/reference/resource/actions) — full action options and bulk patterns
 - [Reference › Behavior › Interactions](/reference/behavior/interactions) — interaction class anatomy
+- [Reference › Behavior › Async Interactions](/reference/behavior/async-interactions) — `async`, progress pages, resuming a crashed run
 - [Reference › Behavior › Policies](/reference/behavior/policies) — `def <action>?` methods
 - [Authorization](./authorization) — policy patterns

data/docs/guides/customizing-ui.md

@@ -132,12 +132,19 @@ class PostCardComponent < Plutonium::UI::Component::Base
 end
 ```
 
-Use it directly in a page, or wire it as a field in the definition:
+Use it directly in a page, or wire it as a field in the definition. A component
+with its own constructor takes the block form — you build it, so you decide what
+it receives:
 
 ```ruby
-display :card, as: PostCardComponent
+display :card do |field|
+  PostCardComponent.new(post: field.object)
+end
 ```
 
+`as: SomeComponent` is for a *field* component, which Plutonium constructs with
+the field builder (`Phlexi::Form::Components::Base` / `Phlexi::Display::Components::Base`) — see the reference below.
+
 → See [Reference › UI › Components](/reference/ui/components).
 
 ## Phlexi themes (recolor without rewriting)

data/docs/guides/index.md

@@ -34,6 +34,7 @@ aside: false
     ]},
     { group: 'Quality', items: [
       { name: 'Testing', link: '/plutonium-core/guides/testing' },
+      { name: 'Performance', desc: 'N+1 queries and eager loading.', link: '/plutonium-core/guides/performance' },
       { name: 'Troubleshooting', link: '/plutonium-core/guides/troubleshooting' },
     ]},
   ]"

data/docs/guides/kanban.md

@@ -44,7 +44,7 @@ end
 
 ```ruby
 class Task < ApplicationRecord
-  include Plutonium::Positioning
+  include Plutonium::Positioning::Model
 
   positioned_on :position, scope: :status
   # ^^ auto-assigns position on create; reposition! scopes to the same status
@@ -390,15 +390,17 @@ There is no card "snap-back" to worry about on cancel — native drag never move
 
 By default Plutonium uses decimal fractional positioning: cards always slot exactly where you drop them without ever renumbering the whole column. You need:
 
-1. A `decimal` database column (precision ≥ 10, scale ≥ 6 recommended).
-2. `include Plutonium::Positioning` in the model.
+1. A `decimal` database column — use the `t.position` helper (`precision: 16, scale: 8`). Hand-rolling it, keep `scale` at **8 or more**: `scale: 6` exactly matches the `1e-6` rebalance threshold and the last subdivision can round into a neighbour.
+2. `include Plutonium::Positioning::Model` in the model.
 3. `positioned_on :position, scope: :status` — the `scope:` option groups positions by the grouping attribute so cards in different columns don't compete.
 
 ### Position modes
 
+`position_on` is the same verb inside and outside `kanban do…end`. Declared on the **definition** it makes the resource's index table and card grid [drag-reorderable](/reference/positioning); declared inside the board it configures the board. A board that declares none **inherits the definition's** (falling back to `:position`, Mode A), so a resource that already reorders in its table needs nothing extra here. Declaration order in the class body doesn't matter — the board resolves this lazily.
+
 ```ruby
 kanban do
-  # Mode A (default) — delegate to Plutonium::Positioning.
+  # Mode A (default) — delegate to Plutonium::Positioning::Model.
   # Uses :position attribute, requires the model concern.
   position_on :position
 
@@ -422,7 +424,7 @@ kanban do
 end
 ```
 
-See [Positioning reference](/reference/kanban/positioning) for the full API and the rebalancing behavior when the decimal gap is exhausted.
+See [Positioning reference](/reference/kanban/positioning) for the full API and the rebalancing behavior when the decimal gap is exhausted, and [Positioning & drag-to-reorder](/reference/positioning) for the table/grid side of the same feature.
 
 ---
 

data/docs/guides/nested-resources.md

@@ -67,11 +67,21 @@ Plutonium prefixes nested routes with `nested_` so they don't conflict with top-
 
 `has_one` associations get singular routes — index redirects to show (or new if no record exists).
 
+Every routable association gets one by default. To draw only some of them:
+
+```ruby
+register_resource ::Company, associations: %i[properties company_profile]
+```
+
+Set `config.nested_association_routes = :declared` to make that the rule, so a
+resource naming none gets none. See [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources#declaring-which-associations-get-routes).
+
 ## What Plutonium does automatically
 
 1. **Resolves the parent** via `current_parent`, authorized for `:read?`.
 2. **Scopes queries** via the parent association (`company.properties` for `has_many`; `where(company_id: ...)` for `has_one`).
-3. **Assigns the parent** on create (injected into `resource_params`).
+3. **Assigns the parent** on create (injected into `resource_params`), building the
+   record on the parent's association so a scoped association supplies its defaults.
 4. **Hides the parent field** in forms and displays.
 
 No hidden fields. No manual scoping.

data/docs/guides/performance.md

@@ -0,0 +1,104 @@
+# Performance: N+1 Queries
+
+Plutonium renders association values for you: a `display :author`, a table `column :organization`, a grid or kanban card showing a related name. Reading an association off a record that wasn't loaded with it costs a query, so an index page runs one query for the page plus one per row per association.
+
+## Spotting it
+
+Tail the log and reload an index. A run of near-identical `SELECT * FROM users WHERE id = ?` lines, one per row, is the signature.
+
+```bash
+tail -f log/development.log
+```
+
+[`bullet`](https://github.com/flyerhzm/bullet) reports them in development if you'd rather be told than look.
+
+The cost matters most where each query is a network round trip. On Postgres or MySQL an index page can spend most of its time waiting; on SQLite the same page is cheaper, though the query count is identical. Either way the count grows with page size, so a listing that is fine at 20 rows may not be at 200.
+
+## Collections preload themselves
+
+Index pages, kanban boards and CSV exports already eager-load the associations and attachments they render. The field set comes from the policy, so the framework knows it before the collection loads and can preload exactly those. Nothing to declare, and nothing to keep in step when a field is added or removed.
+
+Each rendering passes its own field set, because they differ: the index renders its permitted attributes, an export renders `permitted_attributes_for_export`, and a kanban card renders its `card_fields`.
+
+It covers every association kind — `belongs_to`, `has_one`, `has_many` — and attachments on both ActiveStorage and Shrine.
+
+Turn it off globally:
+
+```ruby
+# config/initializers/plutonium.rb
+Plutonium.configure do |config|
+  config.auto_eager_load_collections = false
+end
+```
+
+Or per resource:
+
+```ruby
+class PostsController < ::ResourceController
+  private
+
+  def auto_eager_load_collections? = false
+end
+```
+
+## Eager loading by hand
+
+Anything the framework can't see still needs declaring: an association read inside a custom column block, or one rendered on a show page.
+
+### One listing
+
+Override `filtered_resource_collection`. `super` keeps authorization scoping, search, filters, scopes and sorting:
+
+```ruby
+class PostsController < ::ResourceController
+  private
+
+  def filtered_resource_collection = super.includes(:author, :category)
+end
+```
+
+See [Behavior › Controllers](/reference/behavior/controllers#index-query-hook).
+
+### Everywhere
+
+When an association is read on a show page, an export or a typeahead, put it in the policy's `relation_scope`:
+
+```ruby
+class PostPolicy < ResourcePolicy
+  relation_scope do |relation|
+    default_relation_scope(relation).includes(:author, :category)
+  end
+end
+```
+
+A custom `relation_scope` must still call `default_relation_scope`, or scoping is dropped. See [Behavior › Policies](/reference/behavior/policies).
+
+## Automatic eager loading
+
+For the cases above that the framework can't resolve for you, [Goldiloader](https://github.com/salsify/goldiloader) removes the bookkeeping. It hooks association traversal: reading `post.author` on a record from a collection loads that association for the whole collection in one query. No `includes` anywhere.
+
+```ruby
+# Gemfile
+gem "goldiloader"
+```
+
+It works without per-model configuration. Before adding it:
+
+- It assumes uniform access. Reading an association on one record loads it for every record, which over-fetches when only one row needed it.
+- `has_one` with an order and a limit is a sharp edge: eager loading applies `LIMIT 1` to the whole query rather than per parent.
+- It disables itself for associations declared with `limit`, `offset` or `finder_sql`.
+- Opt out per query (`Post.all.auto_include(false)`), per association (`has_many :comments, -> { auto_include(false) }`) or globally (`Goldiloader.globally_enabled = false`).
+
+[`ar_lazy_preload`](https://github.com/DmitryTsepelev/ar_lazy_preload) takes the same idea from the other end, preloading lazily on first access, with `ArLazyPreload.config.auto_preload = true` for automatic behaviour everywhere. Its docs warn that enabling it on an existing app can surface edge cases.
+
+## Work that does not belong in a request at all
+
+Eager loading fixes a page whose queries are wasteful. It does nothing for one that is simply doing too much work: archiving thousands of records, building a report, waiting on a third party.
+
+Those need to leave the request rather than be optimised inside it. An interaction declares `async` and dispatches a background run, and the user gets a progress page instead of a spinner they cannot leave: [Async Interactions](/reference/behavior/async-interactions).
+
+## Related
+
+- **Search fallback.** A resource with no `search` block falls back to a leading-wildcard `LIKE`, which cannot use a b-tree index. Write an explicit `search` block for large tables — see [Resource › Query](/reference/resource/query#search).
+- **Page size.** Query cost scales with rows per page.
+- [Async Interactions](/reference/behavior/async-interactions) — moving slow work out of the request

data/docs/guides/user-invites.md

@@ -73,7 +73,7 @@ configure do
   login_redirect "/welcome"
 
   after_login do
-    session[:after_welcome_redirect] = session.delete(:login_redirect)
+    session[:after_welcome_redirect] = session.delete(login_redirect_session_key)
   end
 end
 ```

data/docs/guides/wizards.md

@@ -79,6 +79,10 @@ end
 The engine detects failure by a **raised exception**. Non-bang `create`/`save`/`update` return `false` on failure without raising — the engine can't see that, treats the step as successful, and advances, silently losing the data. Always use `create!`/`update!`/`save!`, or call `fail!("message")`.
 :::
 
+::: tip `execute` is a presentation boundary, same as an interaction's
+A wizard is built with `view_context:` too, so everything reachable only through `execute` is reachable only from a wizard run. Steps and `execute` own the *flow* — which screens, in what order, writing what. What the write **means** belongs on the model as soon as a second caller wants it: the API signup that skips onboarding, the admin backfill, the importer. `Company.create!(...)` inline is fine for a one-off; `Company.onboard!(...)` is what you reach for when it isn't. See [Interactions › What an interaction is for](/reference/behavior/interactions#what-an-interaction-is-for) — the rule is identical.
+:::
+
 Each step renders as a focused card with a numbered stepper rail (the terminal `review` shows a finish flag, not a number) and a Back / Next / Cancel strip:
 
 ![A wizard step page — numbered stepper rail, a focused step card with typed inputs, and Back/Next/Cancel navigation](/images/guides/wizards-step.png)
@@ -281,6 +285,7 @@ end
 - `fail!("msg")` aborts the step with a base (form-level) error; `fail!(:field, "msg")` attaches it to a field. Both roll back the step's transaction and re-render with input intact.
 - The engine **always** destroys every `persist`'d record on rollback (Cancel, abandonment-sweep, branch-prune), in reverse order, via `destroy!` (which respects a model's own soft-delete override). `on_rollback` is an **optional, additive** compensating block for side effects the engine can't see (refund a charge, call an external API), and runs **before** the destroy, so `persisted[:key]` is still alive inside it. Don't destroy the tracked record yourself; the engine does.
 - Because `on_submit` writes mid-flow, it isn't atomic across steps — that's why `cleanup_after` + the SweepJob exist. See [Storage & config](/reference/wizard/storage-config) and the [DSL reference](/reference/wizard/dsl#per-step-hooks).
+- `on_submit` / `on_rollback` are **wizard-flow hooks**, not a home for domain logic. They belong to a single wizard step and can't be called from anywhere else, so keep them to *when* and *what gets tracked* — `persist Billing.create!(...)` above is one call to a model. Once "authorize a card and record the billing row" is something the API also does, it becomes `Billing.authorize!(company:, token:)` and the hook shrinks to `persist Billing.authorize!(...)`.
 
 ## Anchored wizards
 
@@ -325,7 +330,10 @@ class WelcomeWizard < Plutonium::Wizard::Base
   review label: "All set?"
 
   def execute
-    current_user.update!(full_name: data.profile.full_name, onboarded_at: Time.current)
+    # User#complete_onboarding! sets the name and stamps onboarded_at. It lives on
+    # the model because the gate below, an admin backfill, and the invite-accept
+    # flow all need to mark a user onboarded — and none of them is a wizard.
+    current_user.complete_onboarding!(full_name: data.profile.full_name)
     succeed.with_message("Welcome aboard!")
   end
 

data/docs/index.md

@@ -8,11 +8,11 @@ aside: false
 
 <HomeStopWriting />
 
-<HomePillars />
-
 <HomeWalkthrough />
 
-<HomeAudienceSplit />
+<HomeFeatureTour />
+
+<HomeWhyPlutonium />
 
 <HomeInTheBox />
 

data/docs/public/templates/experimental.rb

@@ -0,0 +1,34 @@
+# Plutonium's experimental subsystems: wizards and async interactions.
+#
+# Both are off by default — their flags gate their MIGRATIONS as well as their
+# behaviour, so an app that has not opted in has neither table. This turns them
+# on and schedules the recurring jobs each one needs to stay healthy.
+#
+# Kept out of plutonium.rb because it is the baseline install, and these two are
+# marked experimental: their DSL and behaviour may change in a future release.
+# Opting a new app in is a choice, not a default.
+after_bundle do
+  # SweepJob is the only thing that cleans up the partial domain records an
+  # abandoned `on_submit` wizard leaves behind. Unscheduled, those accumulate.
+  unless ENV["SKIP_WIZARDS"]
+    generate "pu:wizards:install"
+    git add: "."
+    git commit: %( -m 'chore: enable wizards') if `git status --porcelain`.present?
+  end
+
+  # --skip-portal: a fresh app has no portals yet, only main_app — the wrong home
+  # for the run resource in an app about to grow them. This turns the subsystem
+  # on; `rails g pu:async_interactions:install --dest=<portal>` connects the
+  # progress page and running banner once there is a portal worth naming.
+  unless ENV["SKIP_ASYNC_INTERACTIONS"]
+    generate "pu:async_interactions:install --skip-portal"
+    git add: "."
+    git commit: %( -m 'chore: enable async interactions') if `git status --porcelain`.present?
+  end
+
+  # Both gate their migration paths on the flags just written, and this process
+  # booted before either existed.
+  rails_command "db:migrate"
+  git add: "."
+  git commit: %( -m 'chore: migrate wizard + async run tables') if `git status --porcelain`.present?
+end

data/docs/public/templates/pluton8.rb

@@ -14,4 +14,18 @@ after_bundle do
     "https://radioactive-labs.github.io/plutonium-core/templates/lite.rb"
   end
   rails_command "app:template LOCATION=#{lite_location}"
+
+  # Wizards + async interactions, last.
+  #
+  # After lite rather than straight after plutonium, because both of these
+  # schedule a recurring job and solid_queue — which lite installs — is what
+  # there is to schedule into. Run earlier and each would print "schedule it
+  # yourself", leaving the app with a subsystem nothing maintains and no second
+  # pass to fix it.
+  experimental_location = if ENV["LOCAL"]
+    "/Users/stefan/Documents/plutonium/plutonium-core/docs/public/templates/experimental.rb"
+  else
+    "https://radioactive-labs.github.io/plutonium-core/templates/experimental.rb"
+  end
+  rails_command "app:template LOCATION=#{experimental_location}"
 end

data/docs/reference/app/portals.md

@@ -128,6 +128,16 @@ For each call, Plutonium auto-generates:
 
 You list every resource the portal exposes. If a resource isn't registered, it has no URLs in that portal — `resource_url_for` will fail.
 
+### Choosing nested associations
+
+Name the associations that get nested routes, and the rest are not drawn:
+
+```ruby
+register_resource ::Post, associations: %i[comments post_detail]
+```
+
+`associations: []` draws none, and a name that is not a routable association fails the boot. Set `config.nested_association_routes = :declared` to make naming them the rule — see [Tenancy › Nested resources](../tenancy/nested-resources#declaring-which-associations-get-routes).
+
 ### Singular (singleton) resources
 
 For resources with no collection — a single per-user `Profile`, app-wide `Settings`, etc.:
@@ -276,13 +286,15 @@ end
 ## Per-portal overrides
 
 ```ruby
-# Definition — different fields per portal
+# Definition — how fields render per portal
 class AdminPortal::PostDefinition < ::PostDefinition
-  input :internal_notes, as: :text     # admins see this; customers don't
   scope :pending_review
+  input :internal_notes, hint: "Not shown to the author"
 end
 
-# Policy — different rules per portal
+# Policy — which fields exist, and who may act
+#          `internal_notes` appears for admins because THIS permits it,
+#          not because the definition above mentions it.
 class AdminPortal::PostPolicy < ::PostPolicy
   include AdminPortal::ResourcePolicy
 

data/docs/reference/auth/accounts.md

@@ -228,6 +228,25 @@ before_create_account_route do
 end
 ```
 
+### Session isolation (multiple account types)
+
+Emitted by the generators; both parts are required for concurrent portal logins.
+
+```ruby
+# app/rodauth/rodauth_plugin.rb — the shared base, once
+enable :session_isolation
+```
+
+```ruby
+# app/rodauth/<name>_rodauth_plugin.rb — once per account type
+session_key_prefix "admin_"           # namespaces EVERY key, account id included
+remember_cookie_key "_admin_remember"
+```
+
+Drop either and signing into one portal evicts the others.
+
+Do **not** also set `session_key`: explicit values bypass `convert_session_key` and so are not prefixed, leaving the account id rotating separately from every other key. Rodauth then raises on any session holding an account id with no `authenticated_by`. See [Guides › Authentication › Multiple portals in one browser](/guides/authentication#multiple-portals-in-one-browser).
+
 ## Related
 
 - [Profile](./profile) — profile resource + SecuritySection component