plutonium 0.63.0 → 0.65.0

data/docs/reference/app/generators.md

@@ -344,7 +344,7 @@ rails g pu:core:install
 
 ### `pu:core:assets`
 
-Set up the custom Tailwind + Stimulus toolchain. Installs npm packages, creates `tailwind.config.js`, imports Plutonium CSS, registers Stimulus controllers.
+Set up the custom Tailwind + Stimulus toolchain. Installs npm packages with the app's package manager (bun, yarn 1, yarn 2+, npm or pnpm, detected from the lockfile, else from what is on PATH), creates `tailwind.config.js`, imports Plutonium CSS, registers Stimulus controllers.
 
 ```bash
 rails g pu:core:assets
@@ -354,7 +354,7 @@ See [UI › Assets](/reference/ui/assets) for what gets configured.
 
 ### `pu:core:update`
 
-Update the plutonium gem and npm package together.
+Update the plutonium gem and npm package together, using the app's package manager.
 
 ```bash
 rails g pu:core:update

data/docs/reference/app/portals.md

@@ -327,6 +327,8 @@ For the full multi-tenancy story, see [Tenancy › Entity scoping](/reference/te
 
 ## Dashboard / non-resource pages
 
+The generated `dashboard#index` is a plain page listing the registered resources. To replace it with a [dashboard](/guides/dashboards) of metric and chart cards, run `rails g pu:dashboard Home --dest=<portal> --at=/`, which swaps the `root to:` line for a `register_dashboard ... at: "/"` registration.
+
 ```ruby
 # config/routes.rb
 AdminPortal::Engine.routes.draw do

data/docs/reference/configuration.md

@@ -1,24 +1,27 @@
 # Configuration
 
-Plutonium is configured through `Plutonium.configure` in an initializer. A generated app has this at `config/initializers/plutonium.rb`:
+Plutonium is configured through `Plutonium.configure` in an initializer. `pu:core:install` writes `config/initializers/plutonium.rb`:
 
 ```ruby
-# config/initializers/plutonium.rb
+# Configure plutonium
+
 Plutonium.configure do |config|
   config.load_defaults 1.0
 
-  # config.shell = :modern
-  # config.navii_host_url = "https://api.navii.dev"
-  # config.auto_eager_load_collections = true
-
-  config.assets.logo       = "plutonium.png"
-  config.assets.favicon    = "plutonium.ico"
-  config.assets.stylesheet = "plutonium.css"
-  config.assets.script     = "plutonium.min.js"
+  # Shell variant: :modern (icon rail), :plain (no rail), or :classic (legacy).
+  config.shell = :modern
+  # Configure plutonium above.
 end
 ```
 
-Access the live config anywhere via `Plutonium.configuration`.
+Everything else is opt-in. Read the live config anywhere via `Plutonium.configuration`, and query development mode with `Plutonium.configuration.development?`.
+
+Other generators edit this file in place. `pu:core:assets` rewrites two lines to point at your own bundles:
+
+```ruby
+config.assets.stylesheet = "application"
+config.assets.script = "application"
+```
 
 ## Versioned defaults
 
@@ -26,41 +29,95 @@ Access the live config anywhere via `Plutonium.configuration`.
 config.load_defaults 1.0
 ```
 
-Loads the baseline defaults for a given framework version. Call this first; later versions layer their changes on top. Read the resolved version with `config.defaults_version`.
+Applies the baseline defaults for a framework version, and every earlier version in order. Call it first, before any option you set yourself, or the defaults overwrite you. `1.0` is currently the only version. Read back what resolved with `config.defaults_version`, which is `nil` until you call this.
+
+Passing a version older than the earliest available raises rather than silently applying nothing.
 
-## Options
+## Core
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `load_defaults(version)` | — | Apply versioned framework defaults. Call first. |
-| `development` | `ENV["PLUTONIUM_DEV"]` | Development mode for the framework itself (local assets, hot reload, verbose errors). Query with `config.development?`. You rarely set this in an app — see [Development mode](#development-mode). |
-| `cache_discovery` | `true` outside `development` env | Cache resource/route discovery. Disable to pick up new resources without a reboot. |
-| `enable_hotreload` | `true` in `development` env | Hot-reload Plutonium components on change. |
+| `development` | `ENV["PLUTONIUM_DEV"]` | Development mode for the framework itself (local assets, hot reload, verbose errors). Query with `config.development?`. Apps rarely set this, see [Development mode](#development-mode). |
+| `cache_discovery` | `true` outside the `development` env | Cache resource/route discovery. Disable to pick up new resources without a reboot. |
+| `enable_hotreload` | `true` in the `development` env | Hot-reload Plutonium components on change. |
+
+## Appearance
+
+| Option | Default | Description |
+|--------|---------|-------------|
 | `shell` | `:modern` | Chrome style: `:modern` (topbar + icon rail), `:plain` (topbar, no icon rail), or `:classic` (legacy header + sidebar, only for upgrades). See [Layouts](./ui/layouts). |
+| `default_page_width` | `:md` | Width of detail-style pages: the show page and resource forms. One of `:sm` `:md` `:lg` `:xl` `:full` (`:full` opts out of any constraint). Index and table pages are unaffected. Override per-resource with `page_width` / `form_width` / `display_width`, see [Definition › Page width](./resource/definition#page-width). |
 | `navii_host_url` | `"https://api.navii.dev"` | Host of the [Navii](https://navii.dev) avatar service used by [`Avatar`](./ui/components#avatar). The component appends `/avatar/:seed`. Repoint to self-host or proxy. |
-| `auto_eager_load_collections` | `true` | Index pages, kanban boards and CSV exports preload the associations and attachments they render. Set `false` to disable globally, or override `auto_eager_load_collections?` in a controller. See [Performance](/guides/performance). |
-| `default_page_width` | `:md` | Width of detail-style pages — the show page and resource forms. One of `:sm :md :lg :xl :full` (`:full` = unconstrained). Index and table pages are unaffected. Override per-resource with `page_width` / `form_width` / `display_width`; see [Definition › Page width](./resource/definition#page-width). |
-| `wizards.width` | `:md` | Default width of wizard step pages. **Independent of `default_page_width`** — a wizard is a self-contained flow, so widening resource pages leaves wizards alone. Override per wizard with `width`. Same size tokens. |
-| `nested_association_routes` | `:detected` | Where a resource's nested routes come from. `:detected` draws one for every `has_many` / `has_one` whose child is registered. `:declared` draws only what `register_resource ..., associations:` names, so a resource that names none gets none. See [Nested resources › Declaring which associations get routes](./tenancy/nested-resources#declaring-which-associations-get-routes). |
 | `assets.logo` | `"plutonium.png"` | Brand logo asset. See [Assets](./ui/assets). |
 | `assets.favicon` | `"plutonium.ico"` | Favicon asset. |
-| `assets.stylesheet` | `"plutonium.css"` | Stylesheet entry. |
-| `assets.script` | `"plutonium.min.js"` | JavaScript entry. |
+| `assets.stylesheet` | `"plutonium.css"` | Stylesheet entry. `pu:core:assets` sets this to `"application"`. |
+| `assets.script` | `"plutonium.min.js"` | JavaScript entry. `pu:core:assets` sets this to `"application"`. |
+
+## Rendering and routing
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `auto_eager_load_collections` | `true` | Index pages, kanban boards and CSV exports preload the associations and attachments they render. The field set comes from the policy, so it is known before the collection loads. Set `false` to disable globally, or override `auto_eager_load_collections?` in a controller. See [Performance](/guides/performance). |
+| `nested_association_routes` | `:detected` | Where a resource's nested routes come from. `:detected` draws one for every `has_many` / `has_one` whose child is a registered resource. `:declared` draws only what `register_resource ..., associations:` names, so a resource that names none gets none. Any other value raises `ArgumentError` rather than drawing the wrong route table for a typo. See [Nested resources](./tenancy/nested-resources#declaring-which-associations-get-routes). |
+| `default_currency_unit` | `nil` | Symbol used when rendering a currency value with no unit set on `has_cents` or the display. `nil` falls back to the i18n `number.currency.format.unit` when the locale defines one, otherwise no symbol. Set a literal like `"£"`, or `false` (or `""`) for no symbol application-wide. See [`has_cents`](./resource/model#has-cents) and [Currency fields](./ui/forms#currency-fields). |
+| `default_phone_country` | `nil` | Default country (ISO2, e.g. `"gh"`) for `as: :phone` inputs that set no `initial_country:`. `nil` leaves it to intl-tel-input, with no country preselected. Stored verbatim; `config.normalized_default_phone_country` returns it downcased, so `"GH"` and `"gh"` are interchangeable. See [Phone fields](./ui/forms#phone-fields). |
+
+## Attachments
+
+`attachment_backend` picks which library stages a file that travels as a plain string: `:active_storage` or `:shrine`. It is the shared default, and each subsystem layers its own override on top, so setting it once covers both and setting one of theirs narrows it to that subsystem.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `attachment_backend` | `nil` | Shared default for staged attachments. `nil` auto-detects. |
+| `wizards.attachment_backend` | `nil` | Overrides the above for wizard attachment fields. `nil` falls through. |
+| `async_interactions.attachment_backend` | `nil` | Overrides the above for run dispatch. `nil` falls through. |
+
+Resolution runs first match wins:
+
+1. The field's own `backend:` option.
+2. The subsystem setting, `wizards.attachment_backend` or `async_interactions.attachment_backend`.
+3. `config.attachment_backend`.
+4. Auto-detection: `:shrine` if `ActiveShrine` is loaded, else `:active_storage`.
+
+Only plain uploads are affected. A direct-upload field already arrives as a token and ignores all of this.
+
+## Wizards
+
+`enabled` gates the subsystem and its migrations. Full detail in [Wizards › Storage & config](./wizard/storage-config).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `wizards.enabled` | `false` | Enable wizards and their migrations. See [Enabling the subsystem](./wizard/storage-config#enabling-the-subsystem). |
+| `wizards.width` | `:md` | Width of wizard step pages. **Independent of `default_page_width`**: a wizard is a self-contained flow, so widening resource pages leaves wizards where they are. Same size tokens. Override per wizard with `width`. |
+| `wizards.cleanup_after` | `14.days` | How long completed and abandoned sessions are kept before `SweepJob` removes them. See [Cleanup & the SweepJob](./wizard/storage-config#cleanup-the-sweepjob). |
+| `wizards.database` | `:primary` | Which database the wizard tables live in. |
+| `wizards.encrypt_data` | `false` | Encrypt every wizard's staged `data` at rest. Off by default because it needs ActiveRecord encryption keys configured. A wizard can still opt in with `encrypt_data` or out with `encrypt_data false` regardless. See [Encryption](./wizard/storage-config#encryption). |
+| `wizards.attachment_backend` | `nil` | See [Attachments](#attachments). |
+
+## Async interactions
+
+`enabled` gates the runs subsystem and its migrations. Full detail in [Async interactions](./behavior/async-interactions).
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `async_interactions.enabled` | `false` | Enable persisted runs and their migrations. See [Enabling](./behavior/async-interactions#enabling). |
+| `async_interactions.queue` | `:default` | ActiveJob queue for run jobs. |
+| `async_interactions.stall_after` | `1.hour` | How long a run may sit with no progress write before `ReapJob` treats it as stalled. See [Stalled runs and ReapJob](./behavior/async-interactions#stalled-runs-and-reapjob). |
+| `async_interactions.attachment_backend` | `nil` | See [Attachments](#attachments). |
 
 ## Development mode
 
-`config.development?` is driven by the `PLUTONIUM_DEV` environment variable, not set in the initializer. It’s primarily for working **on the Plutonium gem** (uses local `src/` assets, enables hot reloading, and shows more detailed errors). Applications generally leave it unset.
+`config.development?` is driven by the `PLUTONIUM_DEV` environment variable, not by the initializer. It is for working **on the Plutonium gem**: it uses local `src/` assets, enables hot reloading, and shows more detailed errors. Applications leave it unset.
 
 ```bash
 export PLUTONIUM_DEV=1
 ```
 
-## Assets
-
-Asset entries live under `config.assets` and point the framework at your compiled stylesheet/script and brand imagery. The `pu:core:assets` generator wires these up. See [Assets](./ui/assets) for the full asset/Tailwind/Stimulus setup.
-
 ## Related
 
 - [Assets](./ui/assets) — stylesheet, script, Tailwind, and design tokens
 - [Layouts](./ui/layouts) — the `shell` option and ejecting chrome
 - [Components › Avatar](./ui/components#avatar) — `navii_host_url`
+- [Wizards › Storage & config](./wizard/storage-config) — the `wizards.*` settings in context
+- [Async interactions](./behavior/async-interactions) — the `async_interactions.*` settings in context

data/docs/reference/dashboard/dsl.md

@@ -0,0 +1,123 @@
+# Dashboard DSL Reference
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+A dashboard is a subclass of `Plutonium::Dashboard::Base`. Everything is declared at class level; an instance is built per request with the view context and is the receiver of every card block.
+
+## Presentation
+
+```ruby
+presents label: "Sales", description: "Orders and revenue", icon: Phlex::TablerIcons::ChartBar
+```
+
+| Key | Default |
+|---|---|
+| `label` | `plutonium.dashboards.<key>.label`, then the class name without `Dashboard` |
+| `description` | `plutonium.dashboards.<key>.description`, then nothing |
+| `icon` | `Phlex::TablerIcons::LayoutDashboard` (used in the sidebar) |
+
+`<key>` is `Class.i18n_key`: the class name underscored without the suffix (`AdminPortal::SalesDashboard` → `admin_portal/sales`). `label` and `description` accept the class-level lazy `t("...")`.
+
+## Board-level options
+
+### refresh(seconds)
+
+Default reload interval for every lazy card. `nil` (the default) disables it.
+
+### width(token)
+
+Page width, one of `:sm`, `:md`, `:lg`, `:xl`, `:full`. Default `:full`.
+
+## Cards
+
+```ruby
+metric(key, **options) { ... }
+chart(key, **options) { ... }
+card(key, **options) { ... }
+```
+
+Keys are unique per dashboard; a duplicate raises at class load. Cards render in declaration order.
+
+### Common options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `label:` | String, lazy `t` | convention, then key titleized | Title |
+| `description:` | String, lazy `t` | convention | Caption |
+| `icon:` | Phlex icon class | none | Shown beside the title |
+| `span:` | `1`..`12`, `:full` | metric `3`, chart `6`, card `6` | Columns of the 12-column grid. `:full` is `12`. On tablets (2 columns) a span of `6` or more takes the row; phones are one column |
+| `lazy:` | Boolean | `true` | `true`: own lazy turbo frame, block runs in a separate request. `false`: inline, block runs in the page request; no frame, never refreshes. See the [guide](/guides/dashboards#lazy-and-inline-cards) |
+| `refresh:` | Integer seconds, or `false` | dashboard `refresh` | Reload interval; requires `lazy: true`. `false` opts the card out of the dashboard's `refresh` |
+| `condition:` | Proc, Symbol | none | Hides the card and 404s its endpoint when false |
+| `href:` | String, Proc | none | Links the title |
+
+Procs (`condition:`, `href:`, the block) run on the dashboard instance with `instance_exec`; a one-argument proc receives the instance instead.
+
+### Locale conventions
+
+```
+plutonium.dashboards.<key>.cards.<card>.label
+plutonium.dashboards.<key>.cards.<card>.description
+plutonium.portals.<portal>.dashboards.<key>...
+```
+
+### metric
+
+The block returns a value or a hash.
+
+| Hash key | Meaning |
+|---|---|
+| `value` | The number or string. `nil` renders `plutonium.dashboard.metric.empty` |
+| `previous` | Computes `change` as a percentage from this value; a zero previous yields no percentage |
+| `change` | Numeric percentage points (`2.5` → `+2.5%`) or a string shown as-is |
+| `trend` | `:up`, `:down`, `:flat`; inferred from the sign of `change` |
+| `change_label` | Caption after the change |
+
+| Option | Values | Meaning |
+|---|---|---|
+| `format:` | `:number` (default), `:currency`, `:percentage`, `:human`, Proc | How `value` is rendered. A proc receives the value and runs on the dashboard |
+| `precision:` | Integer | Decimal places; defaults per format (2 for currency, 1 for percentage, 3 significant for human) |
+| `unit:` | String | Currency symbol for `:currency` |
+| `prefix:` / `suffix:` | String | Wrapped around the formatted value |
+| `positive:` | `:up` (default), `:down` | Which direction is good; drives the change colour |
+| `change_label:` | String | Same as the hash key |
+
+### chart
+
+The block returns Chartkick data: `{label => value}`, `[[label, value], ...]` or `[{name:, data:}, ...]`. `Date` and `Time` keys serialise as ISO strings and draw a time axis.
+
+| Option | Values | Meaning |
+|---|---|---|
+| `type:` | `:line` (default), `:area`, `:column`, `:bar`, `:pie`, `:donut`, `:scatter` | Chartkick chart class |
+| `height:` | CSS length | Drawing area height, default `"240px"` |
+| anything else | | Passed to Chartkick unchanged: `colors`, `stacked`, `min`, `max`, `prefix`, `suffix`, `thousands`, `decimal`, `xtitle`, `ytitle`, `legend`, `curve`, `points`, `discrete`, `download`, `library`, ... |
+
+The `chart` Stimulus controller merges these over Plutonium's defaults: series colours from `--pu-chart-1` to `--pu-chart-8`, axis text from `--pu-text-muted`, grid lines from `--pu-border`, and the empty-data message from `plutonium.js.charts.empty`. A colour-mode switch redraws every chart.
+
+### card
+
+No kind-specific options. The block is `instance_exec`ed in `Plutonium::UI::Dashboard::Custom`, a Phlex component: it emits markup directly, and any method the component does not define is forwarded to the dashboard instance.
+
+## Instance API
+
+| Method | Meaning |
+|---|---|
+| `authorize?` | Override to gate the page and every card. Default `true` |
+| `visible_cards` | Cards whose `condition:` passes |
+| `visible_card!(key)` | The card, or `Plutonium::Dashboard::UnknownCardError` (404) |
+| `refresh_for(card)` | The card's interval, else the dashboard's; `nil` for a card declared `refresh: false` |
+| `view_context` / `helpers` | The Rails view context |
+| `current_user`, `current_scoped_entity`, `scoped_to_entity?`, `params`, `request`, `controller`, `current_engine`, `resource_url_for`, `authorized_resource_scope`, `allowed_to?`, `policy_for`, `registered_resources`, `root_path` | Delegated to the view context |
+
+## Class API
+
+| Method | Meaning |
+|---|---|
+| `cards` | All declared cards, in order |
+| `find_card(key)` / `find_card!(key)` | Lookup by key |
+| `label`, `description`, `icon` | Resolved presentation |
+| `i18n_key`, `route_name` | `admin_portal/sales`, `sales` |
+
+Subclasses inherit the parent's cards and options by copy, so a portal-specific subclass can add cards without touching the parent.

data/docs/reference/dashboard/index.md

@@ -0,0 +1,35 @@
+# Dashboard Reference
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+Reference documentation for Plutonium dashboards: pages of metric, chart and free-form cards, each loaded in its own lazy turbo frame.
+
+## In this section
+
+| Page | What it covers |
+|------|---------------|
+| [DSL](/reference/dashboard/dsl) | `Plutonium::Dashboard::Base`, `presents`, `refresh`, `width`, and the `metric` / `chart` / `card` macros with every option |
+| [Registration](/reference/dashboard/registration) | `register_dashboard`, the routes it draws, the synthesized controller, the sidebar, and the `pu:dashboard` generator |
+
+## Quick start
+
+```ruby
+# packages/admin_portal/app/dashboards/admin_portal/sales_dashboard.rb
+module AdminPortal
+  class SalesDashboard < Plutonium::Dashboard::Base
+    presents label: "Sales", icon: Phlex::TablerIcons::ChartBar
+
+    metric(:orders) { {value: Order.this_month.count, previous: Order.last_month.count} }
+    chart(:revenue, type: :area, span: 8) { Order.group_by_day(:created_at).sum(:total) }
+  end
+end
+
+# packages/admin_portal/config/routes.rb
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"
+end
+```
+
+See the [Dashboards guide](/guides/dashboards) for a full walkthrough.

data/docs/reference/dashboard/registration.md

@@ -0,0 +1,76 @@
+# Dashboard Registration
+
+::: warning Experimental
+Dashboards are experimental: the DSL and behavior may change in a future release.
+:::
+
+## register_dashboard
+
+```ruby
+AdminPortal::Engine.routes.draw do
+  register_dashboard AdminPortal::HomeDashboard, at: "/"       # the portal root
+  register_dashboard AdminPortal::SalesDashboard, at: "sales"  # /admin/dashboards/sales
+  register_dashboard Reports::WeeklyDashboard, at: "reports/weekly", as: "weekly"
+end
+```
+
+| Argument | Meaning |
+|---|---|
+| `at:` | Path under the portal's `dashboards/` segment. `"/"` or `""` mounts at the engine root |
+| `prefix:` | Leading path segment, `"dashboards"` by default. `nil` draws the mount at the bare `at:` path (`/admin/sales`); a string swaps the segment (`prefix: "reports"` → `/admin/reports/sales`). Does not affect helper names |
+| `as:` | Route helper prefix. Defaults to `at:` with slashes replaced, or the class slug for a root mount |
+
+### Routes drawn
+
+```
+GET /dashboards/sales             → DashboardsController#show   sales_dashboard_path
+GET /dashboards/sales/cards/:card → DashboardsController#card   sales_dashboard_card_path
+```
+
+Every path is drawn under `dashboards/`, so a dashboard never shadows a `register_resource` route of the same name (`at: "sales"` next to a `Sale` resource). The route helpers carry no prefix.
+
+With `prefix: nil` nothing reserves the path, so keep `at:` clear of your resource routes yourself.
+
+A root mount draws `root` for the page and `/dashboards/<as>/cards/:card` for the cards (`/<as>/cards/:card` with `prefix: nil`). Replace the portal's generated `root to: "dashboard#index"` line with the registration; two root routes clash. The generated `DashboardController` and its view are then unrouted and can be deleted. The [guide](/guides/dashboards#replacing-the-portal-s-default-page) walks through it.
+
+On a `:path` entity-scoped portal the routes sit inside the scope segment and the helpers are prefixed (`organization_scoped_sales_dashboard_path`). URLs built by the framework thread the current tenant through; when building your own use `dashboard_path_for(SalesDashboard)`, available in controllers, views and components.
+
+### The controller
+
+`register_dashboard` synthesizes `<Portal>::DashboardsController < <Portal>::PlutoniumController` including `Plutonium::Dashboard::Controller` and the portal's `Concerns::Controller`, so it carries the portal's authentication, entity scoping and layout. On the main app it synthesizes a bare `::DashboardsController < ApplicationController`.
+
+Define the class yourself to take over; the synthesized one is only created when the constant is missing.
+
+```ruby
+module AdminPortal
+  class DashboardsController < PlutoniumController
+    include Plutonium::Dashboard::Controller
+
+    before_action { set_page_title("Reports") }
+  end
+end
+```
+
+The concern provides `show` and `card`, `current_dashboard`, `current_dashboard_class`, `authorize_dashboard!` and `dashboard_card_path(card)`.
+
+### The card endpoint
+
+`GET <mount>/cards/:card` runs `authorize?`, looks the key up among the dashboard's cards, checks its `condition:`, and renders the card inside `<turbo-frame id="pu-dashboard-card-<key>">`. Unknown or hidden cards respond 404 (`Plutonium::Dashboard::UnknownCardError`); a denied `authorize?` responds 403. A request without a `Turbo-Frame` header renders the card inside the full layout.
+
+## Sidebar
+
+`registered_dashboards` (a controller helper, also available in components) lists the dashboards mounted on the current engine, and `dashboard_path_for(klass)` builds each page path. The gem's `_resource_sidebar.html.erb` groups them under a Dashboards item (`plutonium.resource.nav.dashboards`) after the Home link (`plutonium.resource.nav.home`), skipping the one mounted at the root, which the Home link already opens.
+
+## Generator
+
+```bash
+rails g pu:dashboard Sales --dest=admin_portal            # /admin/dashboards/sales
+rails g pu:dashboard Home --dest=admin_portal --at=/      # portal root
+rails g pu:dashboard Reporting --dest=main_app --at=reports
+```
+
+Writes `app/dashboards/<portal>/<name>_dashboard.rb` in the package (or `app/dashboards/` for `main_app`) and adds the `register_dashboard` line to the routes. Idempotent.
+
+## Assets
+
+Chart cards load `plutonium-charts.js` (Chart.js and Chartkick) on demand; the file ships with the gem beside `plutonium.js` and is precompiled with it. `Plutonium.configuration.assets.charts_script` names the asset (`"plutonium-charts.min.js"` by default). When `PLUTONIUM_DEV` is set the file comes from the `src/build` manifest like the main bundle.

data/docs/reference/i18n.md

@@ -0,0 +1,239 @@
+# Internationalization
+
+Every string Plutonium renders comes from a locale file, and every label it derives from a key (an action, a scope, a filter, a kanban column, a wizard step, a field's placeholder) can be supplied by one. Nothing in a definition has to change for an app to translate its UI or reword the defaults.
+
+## Where the strings live
+
+Plutonium ships its own text under `config/locales/en/*.yml` in the gem, all under the `plutonium` namespace. Rails loads it at the lowest precedence:
+
+1. The host application's `config/locales` wins over everything.
+2. Package and portal engines' `config/locales`, which Rails loads automatically.
+3. The gem's defaults.
+
+So a portal can reword a Plutonium string for itself, and the app can override the portal.
+
+To change a fixed string, copy its key into your own locale file. The gem's locale files are the catalogue:
+
+```yaml
+# config/locales/en.yml
+en:
+  plutonium:
+    boolean:
+      "true": "On"
+      "false": "Off"
+```
+
+Pagination is the one surface with its own dictionary. The info sentence, the per-page sentence and the nav aria labels come from [Pagy's](https://ddnexus.github.io/pagy/resources/i18n) locale files, which cover about thirty-five languages. Override a Pagy key by adding a file to `Pagy::I18n.pathnames`, not through Rails I18n.
+
+## Switching locale
+
+Plutonium reads `I18n.locale` on every render and never sets it. Set the locale the way any Rails app does, typically an `around_action` in the portal's controller concern:
+
+```ruby
+module AdminPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :switch_locale
+      end
+
+      def switch_locale(&)
+        I18n.with_locale(current_user&.locale || I18n.default_locale, &)
+      end
+    end
+  end
+end
+```
+
+The Pagy locale is synced to `I18n.locale` on each pagination render, so the same switch covers pagination.
+
+## Models and attributes
+
+Model and attribute names follow the Rails convention and already drive every label, column header, page title and flash:
+
+```yaml
+en:
+  activerecord:
+    models:
+      blogging/post:
+        one: "Post"
+        other: "Posts"
+    attributes:
+      blogging/post:
+        title: "Title"
+        published_at: "Published"
+```
+
+The model key is `model_name.i18n_key`: `blogging/post` for `Blogging::Post`. When a model defines `one` and `other`, Plutonium uses them for the plural forms in page titles, empty states and pagination. Without them it falls back to English inflection.
+
+## Fields: placeholder, hint, description
+
+A definition never has to declare help text to make it translatable. When an input or display leaves a slot blank, Plutonium looks it up by convention:
+
+```yaml
+en:
+  plutonium:
+    fields:
+      blogging/post:
+        title:
+          placeholder: "A short, descriptive title"
+          hint: "Shown in search results"
+        body:
+          description: "Rendered as Markdown"
+```
+
+`placeholder` and `hint` apply to forms. `description` applies to displays. The lookup walks the model's ancestors like `human_attribute_name` does, so a key on `blogging/post` also serves an STI subclass.
+
+For each slot the resolution order is:
+
+1. An explicit option on `input` or `display`, then on `field`.
+2. `plutonium.portals.<portal>.fields.<model>.<attr>.<slot>` when rendering inside a portal.
+3. `plutonium.fields.<model>.<attr>.<slot>`.
+4. `helpers.placeholder.<model>.<attr>`, the Rails `form_with` convention, for placeholders only.
+5. Nothing.
+
+An explicit option can still be a translation. Use the definition's class-level `t`, which returns a lazy value resolved on every render in the request's locale:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  input :email, placeholder: t("forms.shared.email_placeholder")
+  input :quantity, hint: t("forms.stock.hint", count: 3)
+end
+```
+
+`t` is sugar over the proc form, which also works and has always been locale-safe:
+
+```ruby
+input :email, placeholder: -> { I18n.t("forms.shared.email_placeholder") }
+```
+
+Never call `I18n.t` directly in a class body. It runs once, at load time, in whatever locale happened to be active. Literal strings remain allowed and are used as they are.
+
+The page-title setters take the same values. Pass a literal to fix it, or the lazy `t` to translate it per request:
+
+```ruby
+index_page_title t("blog.index.title")
+index_page_description t("blog.index.description")
+```
+
+When a definition sets no title, the page falls back to the resource's translated model name.
+
+## Derived labels
+
+Actions, scopes, filters, kanban columns and wizard steps default to a humanized version of their key. Each has a convention key that takes precedence over that fallback, and a `label:` option that takes precedence over both. For an action backed by an interaction, the interaction's explicit `presents label:` also counts as declared and wins over the convention; only the class-name default yields to it.
+
+```yaml
+en:
+  plutonium:
+    actions:
+      blogging/post:
+        publish: "Publish now"
+    scopes:
+      blogging/post:
+        drafts: "Drafts"
+    filters:
+      blogging/post:
+        author: "Written by"
+    kanban_columns:
+      blogging/post:
+        in_review: "In review"
+    wizard_steps:
+      onboarding_wizard:
+        billing: "Billing details"
+```
+
+The model segment is the resource's `model_name.i18n_key`. For wizard steps it is the wizard's `model_name.i18n_key`.
+
+Enum values shown as badges, and the value pills of a select filter, resolve the way Rails resolves enum attribute values, with a Plutonium key as an alternative:
+
+```yaml
+en:
+  activerecord:
+    attributes:
+      blogging/post:
+        status/draft: "Draft"
+        status/published: "Live"
+  plutonium:
+    values:
+      blogging/post:
+        status:
+          archived: "Archived"
+```
+
+## Portals
+
+Every convention key has a portal-scoped variant under `plutonium.portals.<portal>`, where `<portal>` is the package namespace (`admin_portal`). It wins over the global key while rendering inside that portal, and the main app has no portal segment.
+
+Portal packages are Rails engines, so their `config/locales` directory loads automatically. The portal generator scaffolds `packages/<portal>/config/locales/en.yml` with the prefix in place:
+
+```yaml
+# packages/admin_portal/config/locales/en.yml
+en:
+  plutonium:
+    portals:
+      admin_portal:
+        fields:
+          blogging/post:
+            title:
+              placeholder: "Internal working title"
+        actions:
+          blogging/post:
+            publish: "Publish to site"
+```
+
+Feature packages get the same file for their models' names, attributes and field text. Keys without the portal prefix apply everywhere, and load order settles conflicts: the app's files beat a package's, and a package's beat the gem's.
+
+Locale keys vary by portal, never by tenant. Tenant-specific wording is a custom I18n backend concern and is out of scope.
+
+## JavaScript
+
+The Stimulus controllers bundled with the gem read their strings from a JSON blob the layout renders once per page, in the current locale:
+
+```html
+<meta name="pu-i18n" content="{&quot;clipboard&quot;:{&quot;copied&quot;:&quot;Copied!&quot;},...}">
+```
+
+The blob is the `plutonium.js` subtree of the locale merged over the default locale, so overriding a key in YAML changes the bundled JavaScript's text without rebuilding it, and a partially translated locale falls back per key. Host code can read the same blob:
+
+```js
+window.Plutonium.t("plutonium.js.turbo_confirm.confirm")
+window.Plutonium.t("plutonium.js.attachment_input.delete_all", { count: 3 })
+```
+
+Third-party widgets keep their own locale mechanisms. The blob carries optional pass-through settings under `plutonium.js.libraries`:
+
+| Key | Passed to |
+|---|---|
+| `slim_select` | Slim Select `settings` (`placeholderText`, `searchText`, `searchPlaceholder`, `searchingText`) |
+| `flatpickr.locale` | flatpickr's `locale` option. Loading the matching `l10n` bundle is the host's job. |
+| `uppy.strings` | Uppy `locale.strings` |
+| `intl_tel_input` | intl-tel-input `i18n` |
+
+## Auth
+
+Rodauth's own text (labels, buttons, flashes, email subjects) is translated by the [rodauth-i18n](https://github.com/janko/rodauth-i18n) gem, which Plutonium's Rodauth views pick up unchanged because they render through Rodauth's configuration methods. The mailer templates the Rodauth generator copies into your app are plain ERB and are yours to translate.
+
+## Testing
+
+Turn on missing-translation errors in the test environment so a rendered component with a missing key fails instead of printing its key:
+
+```ruby
+# config/environments/test.rb
+config.i18n.raise_on_missing_translations = true
+```
+
+Convention lookups are exempt. They probe with `default: nil` and render nothing when a key is absent, which is the intended behaviour, so they never raise.
+
+## Adding a language
+
+For a second locale, provide:
+
+1. A [rails-i18n](https://github.com/svenfuchs/rails-i18n) locale for Rails' own strings, dates and numbers.
+2. A Pagy dictionary for pagination, which Pagy ships for most languages.
+3. `rodauth-i18n` if you use Rodauth.
+4. A `plutonium` namespace translated from the gem's `config/locales/en/*.yml`.
+5. Your models, attributes and field text under the keys above.
+
+Plutonium itself ships only `en`.