plutonium 0.64.0 → 0.66.0

data/docs/blog/introducing-plutonium-dashboards.md

@@ -0,0 +1,174 @@
+---
+title: "Introducing Plutonium dashboards: metric cards and charts for your Rails admin"
+titleTemplate: "Plutonium Blog"
+date: 2026-10-02
+description: Plutonium now ships dashboards. Declare metric, chart and free-form cards in one Ruby class, mount it with one routes line, and every card loads in its own turbo frame inside your portal's auth and tenancy.
+author: Stefan Froelich
+tags: [announcement, dashboards, charts]
+---
+
+# Introducing Plutonium dashboards: metric cards and charts for your Rails admin
+
+<BlogMeta />
+
+Every portal Plutonium generates opens on a Dashboard page that lists your resources with a record count each. Anything past that, the numbers and charts an admin actually opens the app to see, was yours to build: a controller action, some instance variables, a view. Plutonium 0.65 ships it. A dashboard is a Ruby class of cards, mounted with one line in your routes.
+
+![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/blog/dashboards-overview.png)
+
+## What's in the box
+
+- A class-level DSL with three kinds of card: `metric` for headline numbers, `chart` for charts, `card` for anything else.
+- `register_dashboard`, which draws the routes and a controller that inherits your portal's authentication, tenant scoping and layout.
+- Lazy loading: by default every card is fetched in its own turbo frame, behind a skeleton.
+- A 12-column grid with a default width per kind of card, plus per-card refresh intervals, conditions, links and icons.
+- A `pu:dashboard` generator, and a Dashboards group in the portal sidebar.
+
+## Generate one
+
+```bash
+rails g pu:dashboard Sales --dest=admin_portal
+```
+
+This writes `packages/admin_portal/app/dashboards/admin_portal/sales_dashboard.rb` and adds the registration to the portal's routes:
+
+```ruby
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"
+end
+```
+
+The page is served at `/admin/dashboards/sales`. Pass `--at=/` instead and the dashboard becomes the portal's root page, replacing the generated `root to: "dashboard#index"` (the old `DashboardController` and its view can then go).
+
+## Declare the cards
+
+```ruby
+module AdminPortal
+  class SalesDashboard < Plutonium::Dashboard::Base
+    presents label: "Sales", icon: Phlex::TablerIcons::ChartBar
+
+    refresh 60
+
+    metric(:orders, icon: Phlex::TablerIcons::ShoppingCart, href: -> { resource_url_for(Order, parent: nil) }) do
+      {value: orders.where(created_at: 30.days.ago..).count,
+       previous: orders.where(created_at: 60.days.ago...30.days.ago).count,
+       change_label: "vs. previous 30 days"}
+    end
+
+    metric(:revenue, format: :currency) { orders.sum(:total) }
+
+    metric(:refund_rate, format: :percentage, precision: 1, positive: :down) do
+      {value: 2.1, previous: 1.8}
+    end
+
+    chart(:orders_per_day, type: :area, span: 8) do
+      orders.pluck(:created_at).map(&:to_date).tally.sort.to_h
+    end
+
+    chart(:by_status, type: :donut, span: 4) { orders.group(:status).count }
+
+    card(:latest, span: :full) do
+      ul { latest_orders.each { |order| li { order.number } } }
+    end
+
+    private
+
+    def orders = authorized_resource_scope(Order)
+
+    def latest_orders = orders.order(created_at: :desc).limit(5)
+  end
+end
+```
+
+**Metrics.** The block returns a number, or a hash. Give it a `previous` value and the card computes the percentage change and shows it with a trend arrow. `format:` is `:number`, `:currency`, `:percentage`, `:human` (1.23 Million) or a proc. `positive: :down` says a falling number is the good direction, so the refund rate above, up from 1.8 to 2.1, is styled as bad news.
+
+**Charts.** The block returns [Chartkick data](https://chartkick.com/#data): a hash, an array of pairs, or an array of named series. `type:` is `:line`, `:area`, `:column`, `:bar`, `:pie`, `:donut` or `:scatter`, and every other option passes straight through to Chartkick.
+
+**Custom cards.** The block renders Phlex markup inside the card, for a recent-activity list, a call to action, or whatever the first two do not cover.
+
+**Layout.** The grid is 12 columns wide, so halves, thirds and quarters can share a dashboard. `span:` says how many a card takes. Left out, a metric takes 3 (four to a row) and a chart or custom card takes 6. Above, the area chart takes two thirds of its row and the donut the remaining third. Tablets drop to two columns and phones to one.
+
+Blocks run on the dashboard instance, so private methods are how cards share a query. `authorized_resource_scope(Order)` is the same policy scope your resource pages use: the dashboard counts what this user may see, in this tenant, without restating either rule.
+
+## Every card loads on its own
+
+The page response contains no query results. Each card renders as a lazy turbo frame holding a skeleton:
+
+```html
+<turbo-frame id="pu-dashboard-card-orders" src="/admin/dashboards/sales/cards/orders" loading="lazy">
+```
+
+The browser fetches each frame as it scrolls into view, and the card's block runs in that request. The page paints at once, the cheap cards fill in first, and one expensive aggregate delays itself and nothing else.
+
+![The same dashboard before its frames have loaded: every card is a grey skeleton except the Conversion metric, which is already showing 12.5%](/images/blog/dashboards-loading.png)
+
+The Conversion card in that screenshot is declared `lazy: false`, which makes it inline: its block runs in the page request and the finished card is part of the page response, with no frame, no skeleton and no second request. The price is that the page waits for it. Use it for a number cheap enough that a round trip costs more than the query, and leave everything else lazy. An inline card never refreshes, since there is no frame to reload, and in development and test an exception in its block fails the whole page rather than one frame.
+
+`refresh 60` on the dashboard reloads every lazy card once a minute. `refresh: 10` on a card overrides it, and `refresh: false` keeps an expensive card out of it. Reloads pause while the tab is hidden and catch up when it becomes visible again, so a dashboard left open overnight is not running your aggregates all night.
+
+## Who sees what
+
+A portal dashboard sits behind the portal's login like every other page. To restrict it further, override `authorize?`; a false answer is a 403 from the page and from every card URL.
+
+```ruby
+def authorize? = current_user.admin?
+```
+
+`condition:` hides a single card. Because a card is an endpoint, the condition guards the endpoint too: a hidden card responds 404, so it cannot be fetched by guessing its key.
+
+```ruby
+metric(:margin, format: :percentage, condition: -> { current_user.admin? }) { margin }
+```
+
+On an entity-scoped portal the page and card URLs carry the tenant segment (`/org/1/dashboards/team`) and `current_scoped_entity` is available in every block:
+
+```ruby
+class TeamDashboard < Plutonium::Dashboard::Base
+  metric(:members) { current_scoped_entity.memberships.count }
+end
+```
+
+## When a card breaks
+
+In development and test a card that raises, raises, and you fix the query. In production the card shows a short notice in place of its body and the rest of the dashboard is untouched.
+
+![A dashboard where the Revenue card shows a red "This card could not be loaded." notice while the metrics and the signups chart around it render normally](/images/blog/dashboards-card-error.png)
+
+The failure is written to the Rails log with the dashboard class, the card key and the top of the backtrace, and it is reported through `Rails.error`:
+
+```ruby
+Rails.error.report(
+  error,
+  handled: true,
+  source: "plutonium.dashboard",
+  context: {dashboard: "AdminPortal::SalesDashboard", card: "revenue"}
+)
+```
+
+Both happen because `Rails.error.report` notifies subscribers and writes nothing to the log. An app with no error tracker still gets a log line; an app with Sentry, Honeybadger or AppSignal subscribed gets a handled error it can group by card and alert on.
+
+## Charts without the bundle tax
+
+Charts render with [Chart.js](https://www.chartjs.org/) through Chartkick, which is a lot of JavaScript for an app where most pages are tables and forms. It ships as a separate bundle. A chart card carries the bundle's URL in a data attribute and the `chart` Stimulus controller injects the script the first time a chart connects, so pages without a chart never download it.
+
+Series colours come from the `--pu-chart-1` to `--pu-chart-8` design tokens and are re-read when the colour mode flips. Charts follow your theme in light and dark mode with no per-chart configuration.
+
+## In the sidebar
+
+Registered dashboards are grouped under a Dashboards item in the portal sidebar, with a link per dashboard. A dashboard mounted at the root is what the Home link opens, so it stays out of the group.
+
+![The portal's icon rail with the Dashboards item open, listing Overview and Content](/images/blog/dashboards-sidebar.png)
+
+If your portal has an ejected `_resource_sidebar.html.erb` from an earlier release, the [guide](/guides/dashboards#sidebar) has the block to add.
+
+## A note on URLs
+
+Every dashboard is drawn under a `dashboards/` segment. A portal's URL space already belongs to `register_resource`, and a dashboard at a bare `/admin/sales` is one `Sale` model away from a route collision that Rails resolves silently, by order. If you want the bare path anyway, `prefix: nil` turns the segment off for that mount.
+
+## Experimental, for now
+
+Dashboards ship marked experimental, like kanban, wizards and async interactions: fine to build on, but the DSL may still move before 1.0. If the API fights you, tell me. That feedback still changes things.
+
+## Where to go next
+
+- [Dashboards guide](/guides/dashboards): the worked example, every card option, layout and translations.
+- [Dashboard reference](/reference/dashboard/): the DSL, `register_dashboard` and the routes it draws, and the generator.

data/docs/blog/introducing-plutonium-i18n.md

@@ -0,0 +1,90 @@
+---
+title: "Introducing Plutonium i18n: every string translatable, the Rails way"
+titleTemplate: "Plutonium Blog"
+date: 2026-10-02
+description: The text a framework renders has always been the framework's, not yours. Plutonium now routes every string it draws through a locale file, so translating the UI is a matter of YAML and nothing else.
+author: Stefan Froelich
+tags: [announcement, i18n, rails]
+---
+
+# Introducing Plutonium i18n: every string translatable, the Rails way
+
+<BlogMeta />
+
+You have always been able to translate your own app. Rails has shipped `I18n.t`, per-model attribute names and localized dates since long before you needed them. What you could not translate was the framework on top. The button that says "Create", the "Search..." in the filter box, the flash that a record was saved, the empty-state line, the sentence under the paginator: an admin framework ships those in English, baked into views you adopted the framework precisely so you would never open. Translating them meant forking them.
+
+Plutonium now routes every string it renders through a locale file, and resolves every label it derives from a key through the Rails i18n conventions you already know. Translating the UI is a matter of YAML. Nothing in a definition or a policy changes.
+
+## The strings come from YAML
+
+Plutonium's own text lives under `config/locales/en/*.yml`, in a `plutonium` namespace, loaded at the lowest precedence. Rails' normal load order does the rest: your app's `config/locales` beats a portal's, a portal's beats the gem's. To reword a fixed string, or translate it, copy its key into your own file:
+
+```yaml
+# config/locales/en.yml
+en:
+  plutonium:
+    boolean:
+      "true": "On"
+      "false": "Off"
+```
+
+That one move covers rewording the default "Yes" and "No" in English and translating them to another language. There is no second mechanism to learn for the second case.
+
+## The labels you never wrote translate too
+
+The strings above are the easy half. The interesting half is the text a definition never spells out. An action, a scope, a filter, a kanban column, a field's placeholder: each one defaults to a humanized version of its key, and each has a convention key that a locale file can supply.
+
+```yaml
+en:
+  plutonium:
+    actions:
+      blogging/post:
+        publish: "Publish now"
+    scopes:
+      blogging/post:
+        drafts: "Drafts"
+    fields:
+      blogging/post:
+        title:
+          placeholder: "A short, descriptive title"
+          hint: "Shown in search results"
+```
+
+A field you never annotated is already translatable. You did not declare a placeholder to get one, and you do not declare a key to translate it: Plutonium looks it up by the model's `i18n_key`, the same way `human_attribute_name` walks ancestors, so a key on `blogging/post` also serves its STI subclasses. Model and attribute names flow from the standard Rails `activerecord` keys, which is why column headers, page titles and flashes come along the moment you provide them. Nothing is declared twice, and the exception, an explicit label you do want to spell out, gets a named place: the definition's own `t`, resolved per request in the right locale.
+
+## Switching locale is a Rails around_action
+
+Plutonium reads `I18n.locale` on every render and never sets it, so you switch the way you would in any Rails app. The dummy app's admin portal wires an `EN | ES` toggle into the top bar and remembers the choice per session:
+
+```ruby
+included do
+  around_action :switch_locale
+end
+
+def switch_locale(&)
+  session[:locale] = params[:locale] if params[:locale].present?
+  locale = session[:locale].to_s.to_sym
+  locale = I18n.default_locale unless I18n.available_locales.include?(locale)
+  I18n.with_locale(locale, &)
+end
+```
+
+Pick ES and the portal answers in Spanish: the heading, the search box, the filters and scopes, the column headers, the row and page actions, the status badges, the pager and the CRUD flashes. The heading translates because the definition sets it with the same lazy `t`, `index_page_title t("blog.index.title")`, that inputs and labels use. Two things stay English by design: the record data, because it is yours and not the framework's, and any label a definition hardcodes as a plain string, like the `column :user, label: "Author"` you can see in the shot sitting next to the translated `Autor`.
+
+![The dummy admin portal rendered in Spanish, with the EN | ES switch in the top bar](/images/blog/i18n-es-admin.png)
+
+## Even the parts that aren't Rails views
+
+Two surfaces never touch Rails' server-side `t`, and both come along.
+
+The Stimulus controllers bundled with the gem read their strings from a JSON blob the layout renders once per page in the current locale. Override a key in YAML and the bundled JavaScript's text changes with it, no rebuild. And pagination, which has its own dictionary, is translated by [Pagy](https://ddnexus.github.io/pagy/resources/i18n) in about thirty-five languages out of the box. Plutonium syncs Pagy's locale to `I18n.locale` on every render, so the same `around_action` that switched the chrome switched the pager, in the screenshot above, for free.
+
+## Ship a half-translated locale
+
+You do not have to finish a language before you use it. The dummy demo translates the blog-posts screen and leaves the rest of the app, the dates, and Rodauth's own flashes to fall back to English through `config.i18n.fallbacks`. That matters more than it sounds: the dummy's test environment turns on `raise_on_missing_translations`, as many apps do, so a page under a half-done locale would otherwise blow up on the first key you had not reached yet. With fallbacks on, a found-via-fallback string is not missing. Translate the screens your users live on first, ship it, and fill in the rest as you go.
+
+## Adding a language
+
+A full second locale is the usual Rails checklist: a [rails-i18n](https://github.com/svenfuchs/rails-i18n) locale for dates and numbers, a Pagy dictionary, `rodauth-i18n` if you use Rodauth, the `plutonium` namespace translated from the gem's English files, and your own models and attributes. Plutonium itself ships only English, and hands you the door to the rest.
+
+The [internationalization reference](/reference/i18n) has the full key catalogue and the exact resolution order for every slot.

data/docs/blog/introducing-plutonium.md

@@ -1,11 +1,10 @@
 ---
 title: "Introducing Plutonium: Rails conventions, past CRUD"
 titleTemplate: "Plutonium Blog"
-date: 2026-08-24
+date: 2026-08-22
 description: Rails made a bargain. Follow the conventions and the framework carries you. Plutonium makes the same bargain about the layer Rails deliberately left alone.
 author: Stefan Froelich
 tags: [announcement, rails, architecture]
-draft: true
 ---
 
 # Introducing Plutonium: Rails conventions, past CRUD
@@ -146,11 +145,11 @@ input :content, as: :markdown
 display :status, as: :badge, colors: {published: :accent, draft: :neutral}
 ```
 
-**Render it inline.** A display takes a block, or a proc that runs inside a Phlex context, so tag methods and Tailwind classes are available without defining a class:
+**Render it inline.** A display takes a block that runs inside a Phlex context, so tag methods and Tailwind classes are available without defining a class:
 
 ```ruby
-display :priority, as: :phlexi_render, with: ->(value, attrs) do
-  span(class: "pu-badge") { value.humanize }
+display :priority do |field|
+  span(class: "pu-badge") { field.value.to_s.humanize }
 end
 ```
 

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

@@ -119,7 +119,7 @@ See [Wizards](/guides/wizards) for the full DSL, including per-step writes, resu
 
 ## 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.
+Kanban did not invent its ordering. It uses the same fractional positioning that powers [drag-to-reorder](/reference/resource/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.
 

data/docs/getting-started/installation.md

@@ -9,7 +9,7 @@ rails new myapp -a propshaft -j esbuild -c tailwind \
   -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
 ```
 
-This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium — plus Rodauth auth, asset pipeline, and initial migrations.
+This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium, plus Rodauth auth, asset pipeline, and initial migrations.
 
 After the template completes:
 
@@ -62,7 +62,7 @@ For account options and customization, see [Reference › Auth](/reference/auth/
 rails generate pu:core:assets
 ```
 
-Installs npm packages, creates `tailwind.config.js` extending Plutonium's config, imports Plutonium CSS, registers Stimulus controllers. Required if you want to customize the theme — see [Reference › UI › Assets](/reference/ui/assets) and [Guides › Theming](/guides/theming).
+Installs npm packages, creates `tailwind.config.js` extending Plutonium's config, imports Plutonium CSS, registers Stimulus controllers (`registerControllers(application)`, which your own JS bundle must keep), and points `config.assets.stylesheet` / `script` at your `application` bundles. Until then the app serves the gem's prebuilt CSS and JS, so it is required for custom CSS, brand colors or your own Stimulus controllers. It needs `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` (an app created with `-j esbuild -c tailwind` plus Stimulus). See [Reference › UI › Assets](/reference/ui/assets) and [Guides › Theming](/guides/theming).
 
 ## Verify
 
@@ -99,6 +99,6 @@ bin/dev
 
 ## Next steps
 
-- [Tutorial](./tutorial/) — build a complete blog application step-by-step
-- [Adding resources](/guides/adding-resources) — create your first resource
-- [Creating packages](/guides/creating-packages) — organize code into feature and portal packages
+- [Tutorial](./tutorial/): build a complete blog application step-by-step
+- [Adding resources](/guides/adding-resources): create your first resource
+- [Creating packages](/guides/creating-packages): organize code into feature and portal packages

data/docs/getting-started/tutorial/02-first-resource.md

@@ -118,7 +118,7 @@ rails db:prepare
 
 ## Creating a Portal
 
-Resources need a portal to be accessible via the web. Let's create a public admin portal so we can explore the UI right away — we'll add authentication in [Chapter 3](./03-authentication).
+Resources need a portal to be accessible via the web. Let's create a public admin portal so we can explore the UI right away; we'll add authentication in [Chapter 3](./03-authentication).
 
 ```bash
 rails generate pu:pkg:portal admin --public
@@ -149,9 +149,9 @@ Visit `http://localhost:3000/admin/blogging/posts`. You should see an empty post
 
 ![Empty posts index](/images/tutorial/02-empty-index.png)
 
-Click "New" — the form is automatically generated from your model's attributes. By default Plutonium opens it as a slideover (right) so you keep the index visible; visiting `/admin/blogging/posts/new` directly renders the same form as a standalone page (left):
+Click "New": the form is automatically generated from your model's attributes. By default Plutonium opens it as a slideover (right) so you keep the index visible; visiting `/admin/blogging/posts/new` directly renders the same form as a standalone page (left):
 
-| Default — slideover from index | Standalone page (direct URL) |
+| Default: slideover from index | Standalone page (direct URL) |
 |:--:|:--:|
 | ![Slideover new form](/images/tutorial/02-new-form-modal.png) | ![Standalone new form](/images/tutorial/02-new-form.png) |
 

data/docs/getting-started/tutorial/03-authentication.md

@@ -14,7 +14,7 @@ Plutonium integrates Rodauth seamlessly with its portal system.
 
 ## Installing Rodauth
 
-Run the Plutonium Rodauth installer once per app — it creates the Rodauth app, plugin, and initializer:
+Run the Plutonium Rodauth installer once per app. It creates the Rodauth app, plugin, and initializer:
 
 ```bash
 rails generate pu:rodauth:install
@@ -24,7 +24,7 @@ rails generate pu:rodauth:install
 
 ## Creating an Account Type
 
-Plutonium supports multiple account types. For admins, use the dedicated `pu:rodauth:admin` generator — it's a preset on top of `pu:rodauth:account` that enables 2FA, lockout, audit logging, and disables public signup:
+Plutonium supports multiple account types. For admins, use the dedicated `pu:rodauth:admin` generator. It's a preset on top of `pu:rodauth:account` that enables 2FA, lockout, audit logging, and disables public signup:
 
 ```bash
 rails generate pu:rodauth:admin admin
@@ -71,8 +71,8 @@ rails generate pu:pkg:portal admin --auth=admin --force
 
 This updates two files:
 
-- `packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb` — swaps `include Plutonium::Auth::Public` for `include Plutonium::Auth::Rodauth(:admin)`, giving you `current_user`, `logout_url`, and `profile_url` helpers throughout the portal.
-- `packages/admin_portal/config/routes.rb` — wraps the engine mount in a routes-level constraint:
+- `packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb`: swaps `include Plutonium::Auth::Public` for `include Plutonium::Auth::Rodauth(:admin)`, giving you `current_user`, `logout_url`, and `profile_url` helpers throughout the portal.
+- `packages/admin_portal/config/routes.rb`: wraps the engine mount in a routes-level constraint:
 
   ```ruby
   constraints Rodauth::Rails.authenticate(:admin) do
@@ -80,9 +80,9 @@ This updates two files:
   end
   ```
 
-The routes constraint is what actually gates access — unauthenticated requests to `/admin/*` are redirected to `/admins/login` before they hit any controller or policy.
+The routes constraint is what actually gates access: unauthenticated requests to `/admin/*` are redirected to `/admins/login` before they hit any controller or policy.
 
-(If you prefer not to regenerate, you can apply both edits by hand — they're shown above.)
+(If you prefer not to regenerate, you can apply both edits by hand; they're shown above.)
 
 ## Testing Authentication
 
@@ -164,7 +164,7 @@ Now we can add the author relationship to our Post model. Generate a migration:
 rails generate migration AddUserToBloggingPosts user:belongs_to
 ```
 
-Update the migration to add the foreign key:
+Update the migration to add the foreign key (keep the `Migration[x.y]` version Rails generated for your app):
 
 ```ruby
 class AddUserToBloggingPosts < ActiveRecord::Migration[8.0]

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

@@ -28,8 +28,13 @@ Let's implement basic CRUD permissions:
 
 ```ruby
 class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # Anyone can view published posts
+  # Anyone can open the list; relation_scope (below) decides which posts it holds
   def read?
+    true
+  end
+
+  # A single post: published, or your own
+  def show?
     record.published? || owner?
   end
 
@@ -56,6 +61,8 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
 end
 ```
 
+`read?` also backs `index?`, which is checked against the `Blogging::Post` class rather than a post, so `record.published?` there would raise `NoMethodError` on the list page. Record-state checks go in `show?`, `update?` and `destroy?`, which always receive the post.
+
 ## Understanding the Policy Context
 
 Inside a policy, you have access to:
@@ -63,13 +70,13 @@ Inside a policy, you have access to:
 | Accessor | Description |
 |----------|-------------|
 | `user` | The current authenticated user |
-| `record` | The resource being authorized |
+| `record` | The resource being authorized (the resource class on collection routes such as index and new) |
 | `entity_scope` | Parent record for scoping (e.g., Organization in multi-tenant apps) |
 
 ```ruby
 def some_permission?
   user          # => Current user (from authentication)
-  record        # => The Post instance being checked
+  record        # => The Post instance being checked (Blogging::Post on index/new)
   entity_scope  # => Parent record for multi-tenancy (or nil)
 end
 ```
@@ -101,6 +108,12 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
       [:title] # Limited view for unpublished posts
     end
   end
+
+  # The table is built from the class, not a post, so this must not touch `record`
+  # (without it, index falls back to permitted_attributes_for_read and raises)
+  def permitted_attributes_for_index
+    [:title, :published, :created_at, :user]
+  end
 end
 ```
 
@@ -108,7 +121,7 @@ end
 
 Control which records appear in listings:
 
-`relation_scope` is a macro — it takes a block. Writing it as a plain instance
+`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.
 
@@ -148,6 +161,10 @@ class AdminPortal::Blogging::PostPolicy < ::Blogging::PostPolicy
     true
   end
 
+  def show?
+    true
+  end
+
   def update?
     true
   end

data/docs/getting-started/tutorial/05-custom-actions.md

@@ -79,11 +79,11 @@ end
 
 ## Testing the Action
 
-Open any unpublished post and click **Actions** in the top-right — the "Publish Post" item appears with its Tabler icon:
+Open any unpublished post and click **Actions** in the top-right; the "Publish Post" item appears with its Tabler icon:
 
 ![Publish action in the show page menu](/images/tutorial/05-actions-menu.png)
 
-It also shows on each table row's `⋮` menu — same action, available wherever the record is rendered:
+It also shows on each table row's `⋮` menu, same action, available wherever the record is rendered:
 
 ![Publish action in the row menu](/images/tutorial/05-row-actions.png)
 

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

@@ -13,8 +13,11 @@ Nested resources are resources that belong to a parent resource. In our blog:
 
 ```bash
 rails generate pu:res:scaffold Comment body:text user:belongs_to Blogging/Post:belongs_to --dest=blogging
+rails db:prepare
 ```
 
+Run the migration before connecting the resource to a portal: `pu:res:conn` reads the table's columns to seed the policy's attribute lists.
+
 ## Setting Up the Association
 
 Update the Post model to add the `has_many` association:
@@ -69,11 +72,11 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
 end
 ```
 
-The post show page now has tabs — **Details** and **Comments** — driven by the associations you permit:
+The post show page now has tabs, **Details** and **Comments**, driven by the associations you permit:
 
 ![Post show page with Details and Comments tabs](/images/tutorial/06-post-with-comments.png)
 
-Clicking **Comments** opens the nested index for that post — a complete sub-resource view with its own paginated table, "New" button, and row actions:
+Clicking **Comments** opens the nested index for that post: a complete sub-resource view with its own paginated table, "New" button, and row actions:
 
 ![Nested comments index](/images/tutorial/06-comments-tab.png)
 

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

@@ -168,11 +168,11 @@ Now you have two portals:
 | Admin | `/admin` | Admin | All posts |
 | Author | `/author` | User | Own posts only |
 
-Log in at `/users/login` with the user account and you land on the Author Portal dashboard — the same chrome as the Admin Portal but mounted at `/author`, gated by `Rodauth::Rails.authenticate(:user)`:
+Log in at `/users/login` with the user account and you land on the Author Portal dashboard, the same chrome as the Admin Portal but mounted at `/author`, gated by `Rodauth::Rails.authenticate(:user)`:
 
 ![Author Portal dashboard](/images/tutorial/07-author-dashboard.png)
 
-The posts list lives at `/author/blogging/posts` — same `Blogging::Post` resource, different portal context (and once you add the scoping policy below, scoped to the logged-in author):
+The posts list lives at `/author/blogging/posts`: same `Blogging::Post` resource, different portal context (and once you add the scoping policy below, scoped to the logged-in author):
 
 ![Author Portal posts index](/images/tutorial/07-author-portal.png)