plutonium 0.62.2 → 0.64.0

data/docs/blog/plutonium-and-ai-agents.md

@@ -0,0 +1,48 @@
+---
+title: "Plutonium wasn't built for AI agents. Rails conventions are why they work."
+titleTemplate: "Plutonium Blog"
+date: 2026-09-10
+description: The conventions were chosen for human reasons. Assistants turned out to be unusually accurate inside them, which was informative about both the framework and the docs.
+author: Stefan Froelich
+tags: [ai, conventions, rails]
+draft: true
+---
+
+# Plutonium wasn't built for AI agents. Rails conventions are why they work.
+
+<BlogMeta />
+
+There is an "For AI Agents" page in these docs and a `.claude/skills/` directory in the repo, so it is fair to assume this was designed as an AI thing. It was not. The order of events was the other way round, and the order matters, because it is the part that generalises to your own codebase.
+
+I built Plutonium convention-heavy for ordinary human reasons: fewer decisions per feature, one place to change anything, code that reads the same across projects. Then I noticed that assistants were unusually accurate inside it, in a way they were not inside the hand-rolled Rails apps I had written before. That was interesting enough to investigate, and then to lean into.
+
+## Why the accuracy is higher
+
+Not because of anything clever. Because there is less to guess.
+
+Most of what an assistant gets wrong in an unfamiliar Rails app is not syntax. It is context it cannot see: which of four places a filter should live, whether this project puts business logic in the model or a service, what the local naming convention is, what already exists that it should not duplicate.
+
+A Plutonium app answers most of those structurally:
+
+- **The layers are named and their jobs are disjoint.** Model, definition, policy, controller, interaction. "Which fields are visible" has exactly one home, and it is not the one an assistant would guess from a filename.
+- **Most behaviour is derived, not declared.** Field types come from columns, required markers from validations, select choices from `inclusion:`, preloads from the policy's permitted fields, tenant scope from associations. There is less code to write, so there is less code to get wrong.
+- **Overrides are plain class inheritance.** `AdminPortal::PostDefinition < ::PostDefinition`. No registry, no precedence rules, no merge semantics that have to be learned before you can predict an outcome.
+- **The generators produce conventional files.** An assistant that runs `pu:res:scaffold` starts from a correct skeleton rather than an invented one.
+
+None of that was designed with a model in mind. It is just that "predictable enough that a newcomer can infer the next step" and "predictable enough that a language model can" turn out to be close to the same property.
+
+## What I did after noticing
+
+Leaned in, with three things that cost the project nothing if you never use them.
+
+**Skills.** `.claude/skills/` holds a router plus targeted guides. They are not documentation-for-humans copied into a folder. They are written as instructions: what to read before acting, what to ask, the mistakes that cost the most, and explicit gates that say "inspect the app yourself rather than asking the user to describe it."
+
+**`llms.txt` and per-page markdown twins.** Every docs page has a raw `.md` sibling, plus generated `llms.txt` and `llms-full.txt`. An agent can pull exact source rather than scraping rendered HTML.
+
+**A router skill that says what *not* to write.** This is the one that mattered most. The failure mode of an eager assistant is over-declaring: writing `field :title` when the type is already detected, restating a scope, redeclaring an input that auto-detection already got right. So the router now leads with the rule that a declaration matching the detected default is dead code.
+
+## If you do not care about AI
+
+You lose nothing. There is no AI runtime in Plutonium, no model calls, no telemetry, no feature that only works with an assistant. The skills are markdown files you can ignore, and `llms.txt` is a static artifact of the docs build.
+
+What is left is the thing that was there first: a framework where the conventions are strong enough that the next step is usually inferable. That was worth having when the only inference engine was a new team member reading the codebase on their first day.

data/docs/blog/realtime-is-one-line-and-four-dependencies.md

@@ -0,0 +1,70 @@
+---
+title: "Plutonium realtime is one line, and four things that line assumes"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-17
+description: The server broadcasts whether or not anyone can hear it. A feature that half-works in development and does nothing in production deserves its caveats up front.
+author: Stefan Froelich
+tags: [kanban, hotwire, actioncable]
+draft: true
+---
+
+# Plutonium realtime is one line, and four things that line assumes
+
+<BlogMeta />
+
+Turning on realtime for a kanban board is one line:
+
+```ruby
+kanban do
+  realtime true
+  # ...
+end
+```
+
+Move a card and every other viewer of the same board sees it. That is true, and it is also the kind of claim that earns a framework a bad afternoon, because the line does not fail loudly when its assumptions are missing. It fails by working perfectly on the server and reaching nobody.
+
+So here is the honest version.
+
+## What the line actually does
+
+Two things, both server-side.
+
+It renders a `<turbo-cable-stream-source>` element subscribing the page to a stream. And after a successful move, it broadcasts the updated column frames to that stream.
+
+Stream names are tenant-scoped, so viewers in different tenants cannot receive each other's boards. That part is not optional and not something you can misconfigure into a leak.
+
+What it does **not** do is give the browser anything capable of receiving a broadcast.
+
+## The four assumptions
+
+**1. An ActionCable client in your JavaScript.** This is the one that bites. Plutonium's bundled JavaScript ships `@hotwired/turbo` only, with no cable client. Without `@hotwired/turbo-rails` or `@rails/actioncable` in your pack, the `<turbo-cable-stream-source>` element renders and never connects. No error, no console warning, no failed request to look at. The element is simply inert.
+
+**2. The gems.** `turbo-rails` for `Turbo::StreamsChannel`, and ActionCable, which Rails already includes.
+
+**3. A cable adapter in `config/cable.yml`.** `async` is fine for a single-process dev server. In multi-process production it is a trap: a broadcast from one worker never reaches clients connected to another, so realtime works for roughly one in N users depending on which worker they landed on. Redis or Solid Cable for anything real.
+
+**4. ActionCable mounted.** At `/cable`, the usual place.
+
+## Why this is worth a blog post rather than a footnote
+
+Because of the shape of the failure.
+
+Miss any of these and the feature does not break. Your board still works. Drags still persist, the server still broadcasts, the code path still runs, tests that check the move endpoint still pass. The only symptom is that a second browser window does not update, which is exactly the thing nobody checks after the first time they see it work.
+
+And it very often *does* work the first time, in development, on a single-process server with `async` cable and a dev pack that happened to include turbo-rails. Then it stops working in production, where there are four workers and a different pack, and the bug has no error attached to it.
+
+A feature that degrades silently between environments is worse than one that raises. Raising is a bug report; silence is a support ticket six weeks later titled "does realtime actually work?"
+
+## The design tradeoff underneath
+
+The obvious question is why the framework does not just bundle a cable client and remove three of the four steps.
+
+Because that would ship an ActionCable dependency, a WebSocket connection attempt, and a chunk of JavaScript to every Plutonium app, including the large majority that never turn realtime on. Plutonium's asset bundle is deliberately small and its JavaScript deliberately boring. Paying that cost for everyone so one flag can be a true one-liner is a bad trade.
+
+What the framework owes you instead is to be explicit that the line is not self-sufficient. Which is what the docs now do, and what this post is.
+
+## Checking it
+
+The verification that actually matters takes two browsers and thirty seconds. Open the board in both, move a card in one, watch the other. If it does not move, look for the cable client first: it is the missing piece roughly always, because it is the only one of the four that no other Rails feature would have already forced you to set up.
+
+The rest of realtime, the broadcasting, the tenant scoping, the frame updates, is the part you do not have to think about. The connection is the part you do.

data/docs/blog/two-forms-one-dom-id.md

@@ -0,0 +1,69 @@
+---
+title: "Two forms, one DOM id, and the Rails validation errors that vanished"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-14
+description: A Turbo Stream replaces the first matching element in document order. When two forms on a page share an id, that is rarely the one the user submitted.
+author: Stefan Froelich
+tags: [hotwire, turbo, debugging]
+draft: true
+---
+
+# Two forms, one DOM id, and the Rails validation errors that vanished
+
+<BlogMeta />
+
+The bug report was the worst kind: "sometimes validation errors don't show up." Not an exception, not a 500, no log line. The form submits, the modal sits there, and whatever the server said about the invalid email address goes nowhere.
+
+The cause is one sentence of Turbo's contract, and it is not a bug in Turbo.
+
+## The mechanism
+
+`turbo_stream.replace("resource-form", …)` replaces the element with that id. If more than one element has that id, Turbo takes the first match in document order. The DOM does not enforce id uniqueness, and nothing in Rails warns you.
+
+In an admin UI, duplicate form ids are not exotic. Two ways it happened here:
+
+- A primary modal opens a secondary, stacked modal. Both render a resource form. Both call it `resource-form`.
+- Any index page ships an off-screen Filters slideover with its own form, alongside the CRUD form.
+
+So the server responds to a submission from the *second* form, Turbo finds the *first*, replaces something the user cannot see, and the visible form is untouched. From the user's side, nothing happened. From the logs' side, a 422 rendered and a stream was sent. Everything worked.
+
+That gap between "the server did the right thing" and "the user saw nothing" is why this survives review. There is no failing test to write until you know the failure exists.
+
+## The fix
+
+Ids get scoped to the Turbo frame they render in:
+
+```ruby
+def turbo_scoped_dom_id(base)
+  base = base.to_s
+  case current_turbo_frame
+  when Plutonium::REMOTE_MODAL_FRAME           then "#{base}-primary"
+  when Plutonium::REMOTE_MODAL_SECONDARY_FRAME then "#{base}-secondary"
+  else base
+  end
+end
+```
+
+Outside a modal you get `resource-form`. Inside the primary modal, `resource-form-primary`. Inside the secondary, `resource-form-secondary`. The stream replace derives its target the same way, from the frame the request came in on, so a submission from the stacked modal can only ever address the stacked modal's form.
+
+The Filters slideover stopped borrowing the name entirely and uses `filter-form`, so a CRUD replace cannot reach it regardless of frames.
+
+## Two things that made it harder than it sounds
+
+**Ids had to be resolved at render time, not construction time.** The obvious place to compute the id is when the form component initialises its attributes. Phlex cannot reach `view_context` there, and `current_turbo_frame` comes from the request. So resolution moved into a `form_attributes` override that runs during render, when the frame is actually knowable.
+
+**The id had to be forced rather than merged.** Phlexi's `@namespace.dom_id` prepends a namespace token if you let it merge, which produced ids like `q filter-form`. A space in an id is legal HTML and completely breaks `getElementById`. Forcing the value avoided a bug that would have looked exactly like the one being fixed.
+
+## What generalises
+
+You do not need Plutonium to hit this. You need a Turbo Stream, a component that hardcodes an id, and any situation where that component can appear twice. Modals over modals is the common one. A slideover, a drawer, an inline edit row inside a table that also has a create form: all the same shape.
+
+Three things worth taking away:
+
+**A stream replace is a query, not an address.** `replace("resource-form")` says "find something called this," and it will find something. It is only unambiguous if you have guaranteed uniqueness, which nothing does for you.
+
+**Silence is the tell.** When a form submits and *nothing at all* happens, suspect that something did happen, off-screen. A stream that targets the wrong element is indistinguishable from a stream that was never sent, unless you go looking in the network tab.
+
+**Component ids need a scope.** Any component that hardcodes a DOM id has an implicit assumption that it renders once per page. That assumption is fine right up until the day someone opens it in a modal.
+
+The tests that came with the fix cover the helper in all five frame contexts, including no frame and a non-modal frame. Which is the other half of the lesson: once you know the failure mode, it is trivial to test. The expensive part was believing "sometimes errors don't show up" for long enough to find it.

data/docs/blog/whats-new-async-kanban-wizards.md

@@ -0,0 +1,130 @@
+---
+title: "What's new in Plutonium: async interactions, kanban boards, and wizards"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-07
+description: Three features that close the same gap, where you got most of the way through building something in Rails and then had to leave the framework to finish it.
+author: Stefan Froelich
+tags: [release, async, kanban, wizards]
+draft: true
+---
+
+# What's new in Plutonium: async interactions, kanban boards, and wizards
+
+<BlogMeta />
+
+Three features landed that share a shape. Each one closes a place where you could get most of the way through a feature and then had to drop out of the framework and hand-roll the rest: work that takes too long for a request, a board view, and a form that spans more than one screen.
+
+## Async interactions
+
+An interaction is the button, form, policy gate and outcome in front of an operation. That works right up until the operation does not fit in a request: archiving five thousand records, generating a report, calling a third-party API that takes its time.
+
+The old answer was to write the interaction anyway, enqueue a job from `execute`, invent somewhere to store progress, and build a page to show it. Now you declare the work with `async` and skip all of that:
+
+```ruby
+class Blogging::ArchivePosts < ResourceInteraction
+  presents label: "Archive", icon: Phlex::TablerIcons::Archive
+
+  attribute :resources          # bulk, so perform_on runs once per record
+  attribute :reason, :string
+
+  async do
+    on_failure :continue        # :halt (default) | :continue | :transactional
+
+    def perform_on(post)
+      post.archive!(reason: options["reason"])
+    end
+  end
+end
+```
+
+`async` replaces `execute` entirely. Everything in front of it is unchanged: the interaction still validates its inputs, still gets gated by the same policy method, still renders the same form. Only what happens on submit changes. It persists a run, enqueues it, and redirects to it.
+
+Three things worth calling out.
+
+**The run is a resource.** Register it once per portal:
+
+```bash
+rails g pu:async_interactions:install --dest=admin_portal
+```
+
+Its show page *is* the progress page: a live count, the failures so far, and a banner above the resource's collection while a run is in flight. You wrote none of it.
+
+**Failure has a policy, not a convention.** `on_failure` picks between `:halt` (stop at the first failure), `:continue` (record it and keep going), and `:transactional` (one transaction around the batch, so any failure rolls back everything).
+
+**Permissions are re-derived at perform time, never replayed from dispatch.** The row records who initiated the run and under which tenant, then resolves targets through the policy scope again when the job actually runs. If someone loses access between dispatch and perform, the run respects that. There is [a longer post](/blog/jobs-are-not-permission-snapshots) on why this matters.
+
+It is opt-in: a config flag and a migration.
+
+## Kanban boards
+
+Any resource index can become a drag-and-drop board from a single `kanban do…end` block in the definition:
+
+```ruby
+class TaskDefinition < ResourceDefinition
+  kanban do
+    column :todo,
+      scope: -> { where(status: "todo") },
+      on_enter: ->(r) { r.update!(status: "todo") },
+      role: :backlog
+
+    column :doing,
+      scope: -> { where(status: "doing") },
+      on_enter: ->(r) { r.update!(status: "doing") },
+      wip: 3
+
+    column :done,
+      scope: -> { where(status: "done") },
+      on_enter: :mark_done!,     # Symbol calls record.mark_done!
+      accepts: [:doing]          # only cards from :doing can land here
+  end
+end
+```
+
+ Columns, WIP limits, locked columns and cross-column drop restrictions, all enforced server-side rather than merely hidden in the UI. Each column gets an `+ Add` button that opens the resource's normal new form and drops the new card into that column. Column actions run an interaction against every card in a column. Realtime is one line, and every connected viewer converges on the same board state after a move.
+
+See [Kanban Boards](/guides/kanban) for a complete worked example: migration, model, definition and policy for a task board.
+
+## Wizards
+
+Onboarding, checkout, "create four related records across five screens", a branching questionnaire: multi-step flows are now a single declarative class. Ordered `step`s collect typed data, `condition:` makes steps appear and disappear based on earlier answers, a built-in review step recaps everything before the Finish button, and `execute` commits at the end, atomically by default.
+
+```ruby
+class CompanyOnboardingWizard < Plutonium::Wizard::Base
+  presents label: "Onboard a company", icon: Phlex::TablerIcons::BuildingSkyscraper
+
+  step :company, label: "Company details" do
+    attribute :name, :string
+    input :name
+    validates :name, presence: true
+  end
+
+  step :plan, label: "Plan" do
+    attribute :plan, :string
+    input :plan, as: :radio_buttons, choices: %w[free pro]
+    validates :plan, presence: true
+  end
+
+  review label: "Review & submit"
+
+  def execute
+    company = Company.create!(name: data.company.name, plan: data.plan.plan)
+    succeed(company).with_message("You're all set!")
+  end
+end
+```
+
+The part that matters most is that it reuses the field DSL you already know. `attribute`, `input`, `validates`, `structured_input` and `form_layout` behave exactly as they do in a definition or an interaction. There is no parallel stack to learn and no second way to render a select.
+
+See [Wizards](/guides/wizards) for the full DSL, including per-step writes, resume, and one-time wizards.
+
+## The thing underneath the board
+
+Kanban did not invent its ordering. It uses the same fractional positioning that powers [drag-to-reorder](/reference/positioning) on ordinary index tables, card grids and nested association tables. `positioned_on` on the model says how positions are stored, `position_on` in the definition says the list is orderable, and a drop writes exactly one decimal, the midpoint between its two neighbours. No renumbering sweep across the table.
+
+A board and a sortable table are the same feature wearing different clothes, which is why they share a vocabulary. Positioning itself is stable, not experimental.
+
+## Kanban, wizards and async are marked experimental
+
+Deliberately, and it says so on each page. The features are complete and in use, but the DSLs are new and I would rather rename a method in response to real use than freeze a first guess into a compatibility promise. Positioning is not in that group.
+
+If you build on the experimental three, watch the changelog, and tell me where the API fights you. That feedback still changes things.

data/docs/getting-started/tutorial/04-authorization.md

@@ -108,10 +108,19 @@ end
 
 Control which records appear in listings:
 
+`relation_scope` is a macro — it takes a block. Writing it as a plain instance
+method (`def relation_scope(relation)`) overrides nothing and your scoping is
+silently ignored, so Plutonium raises if you try.
+
+Always compose with `default_relation_scope(relation)`; skipping it raises too,
+because it is what applies parent and tenant scoping.
+
 ```ruby
 class Blogging::PostPolicy < Blogging::ResourcePolicy
   # Called when listing posts
-  def relation_scope(relation)
+  relation_scope do |relation|
+    relation = default_relation_scope(relation)
+
     if admin?
       relation # Admins see everything
     else
@@ -147,8 +156,8 @@ class AdminPortal::Blogging::PostPolicy < ::Blogging::PostPolicy
     true
   end
 
-  def relation_scope(relation)
-    relation # No scope restrictions for admins
+  relation_scope do |relation|
+    default_relation_scope(relation) # No extra restrictions for admins
   end
 end
 ```

data/docs/getting-started/tutorial/06-nested-resources.md

@@ -101,7 +101,9 @@ class Blogging::CommentPolicy < Blogging::ResourcePolicy
   end
 
   # Scope to comments on published posts (or user's own posts)
-  def relation_scope(relation)
+  relation_scope do |relation|
+    relation = default_relation_scope(relation)
+
     relation.joins(:post).where(
       blogging_posts: {published: true}
     ).or(

data/docs/getting-started/tutorial/07-author-portal.md

@@ -84,8 +84,8 @@ Authors should only see and manage their own posts. Create a portal-specific pol
 # packages/author_portal/app/policies/author_portal/blogging/post_policy.rb
 class AuthorPortal::Blogging::PostPolicy < ::Blogging::PostPolicy
   # Authors can only see their own posts
-  def relation_scope(relation)
-    relation.where(user_id: user.id)
+  relation_scope do |relation|
+    default_relation_scope(relation).where(user_id: user.id)
   end
 
   # Authors can always create posts

data/docs/guides/authentication.md

@@ -115,6 +115,78 @@ include Plutonium::Auth::Rodauth(:user)
 
 See [Reference › App › Portals](/reference/app/portals#controller-concern-auth).
 
+## Multiple portals in one browser
+
+A person can hold a session in several portals at once — signed into the admin portal and the customer portal in the same browser, with neither evicting the other. Two settings make that work, and the generators emit both:
+
+```ruby
+# app/rodauth/rodauth_plugin.rb — the shared base
+configure do
+  enable :session_isolation
+end
+```
+
+```ruby
+# app/rodauth/admin_rodauth_plugin.rb — once per account type
+configure do
+  session_key_prefix "admin_"
+  remember_cookie_key "_admin_remember"
+end
+```
+
+Both are required. `session_key_prefix` namespaces *every* session key a configuration touches — the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup` and the rest. `session_isolation` uses that prefix to decide which entries belong to whom, and stops one configuration's login from clearing another's.
+
+::: danger Do not also set `session_key`
+An explicit `session_key` is **not** prefixed (`convert_session_key`, `rodauth/features/base.rb:686` — only the default value passes through it). Setting both leaves the account id on a different name from every other key, so they stop rotating together. A session that holds an account id but no `authenticated_by` makes Rodauth raise on *every request* — `logged_in_via_remember_key?` calls `nil.include?` (`remember.rb:175`).
+
+A config without a prefix at all is also not isolated: its keys are Rodauth's unprefixed defaults, indistinguishable from any other unprefixed config's, so `session_isolation` carries nothing for it.
+:::
+
+::: details Why this is needed
+Rodauth resets the session on every login — including the `remember` feature's `load_memory` autologin — to defend against session fixation, and rodauth-rails implements that reset as a full `reset_session`.
+
+Without `session_isolation`, signing into one portal wipes every other portal's session. And because `RodauthApp#route` calls `load_memory` for *every* configuration on *every* request, the evicted configuration immediately autologins from its remember cookie and evicts the new one right back. The last `load_memory` call in the route block wins permanently, so the other portal can never hold a session at all.
+
+`session_isolation` carries only the *other configurations'* session entries across the reset. The session id is still rotated and application session data is still cleared, so session fixation is still defeated.
+:::
+
+Reading a raw Rodauth session key? Go through its accessor, never the literal — with a prefix set, the literal is the wrong key:
+
+```ruby
+after_login do
+  session[:after_welcome_redirect] = session.delete(login_redirect_session_key) # ✅
+  session[:after_welcome_redirect] = session.delete(:login_redirect)            # ❌ wrong key
+end
+```
+
+**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin and `session_key_prefix` in each account plugin — and **delete the existing `session_key "_x_session"` line** while you're there, for the reason above.
+
+Every key name changes together, so old session cookies stop matching and are ignored — the safe outcome. Keeping the old `session_key` to "preserve" logins is what produces the half-migrated session that crashes.
+
+In practice only *unremembered* sessions drop: `remember_cookie_key` is a cookie name and isn't touched by the prefix, so anyone holding a valid `_x_remember` cookie is restored by `load_memory` on their next request, which writes the new prefixed keys. Expect logouts for users who never ticked "Remember Me", not a full sign-out.
+
+## "Remember me" is opt-in
+
+The login form renders a "Remember Me" checkbox whenever the config enables the `remember` feature, and the config only issues the 14-day cookie when it's ticked:
+
+```ruby
+after_login { remember_login if param_or_nil(remember_param) == remember_remember_param_value }
+```
+
+To go back to remembering everyone whether they asked or not, swap in the unconditional form:
+
+```ruby
+after_login { remember_login }
+```
+
+::: warning Compare the value, don't just check presence
+`param_or_nil(remember_param)` on its own is a truthiness check, and `remember_param` is shared with Rodauth's `/remember` settings page — which submits `forget` and `disable` as well as `remember`. A bare presence check means `remember=disable` would remember you. Compare against `remember_remember_param_value`, as above.
+
+Plutonium's login form also passes `include_hidden: false` to `check_box`, so an unticked box sends nothing at all rather than Rails' default `"0"`. With the value comparison that's belt-and-braces rather than load-bearing (`"0" == "remember"` is already false) — but it keeps a junk param off the wire and keeps the form correct for anyone who reverts the hook to a bare truthiness check.
+:::
+
+Logged-in users can change the setting later on Rodauth's `/remember` page (Remember / Forget / Disable).
+
 ## Customizing the auth flow
 
 All inside `app/rodauth/<name>_rodauth_plugin.rb`, in the `configure do` block:
@@ -185,6 +257,7 @@ user
 - **"You need to set up Rodauth"** — run `pu:rodauth:install` first.
 - **Portal redirects to login even though you're authenticated** — the portal mount constraint references a different Rodauth account than the portal's controller concern uses. Match them up.
 - **Email confirmation never arrives in development** — Plutonium sets ActionMailer to `:test` by default. Check `tmp/letter_opener/` or your mail interceptor. In production, configure SMTP (see above).
+- **Signing into one portal signs you out of another** — or one portal can never stay signed in at all. Missing `enable :session_isolation` and/or `session_key_prefix`; see [Multiple portals in one browser](#multiple-portals-in-one-browser).
 
 ## Related
 

data/docs/guides/authorization.md

@@ -55,6 +55,8 @@ def destroy?
 end
 ```
 
+🚨 **`record` is the resource CLASS on collection routes.** `read?` backs both `show?` (called with the record) and `index?` (called with the class — there is no single record to pass). The same goes for `create?`/`new?`, `export_csv?`, `search?`, and resource-action gates. So `def read? = record.published?` raises `NoMethodError` the moment the index renders. Keep record-state rules out of these methods: filter what the list shows in `relation_scope` (step 6 below), and gate individual records in `show?` (which always receives the record). Record-action methods like `publish?` are safe — they are always evaluated against an instance.
+
 ### 4. Declare attribute permissions
 
 ```ruby

data/docs/guides/creating-packages.md

@@ -147,13 +147,15 @@ Loaded from `config/application.rb`. Migrations from all packages are picked up
 ## 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