plutonium 0.64.0 → 0.66.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6abf981b5e375a2c576de8bfe5fe6448b115753356b6c91f1c3b0ae946e66935
-  data.tar.gz: b519f55b96e20f592baab81b34a633de562dcd8060dbe2bf65cbff7342ae76dd
+  metadata.gz: b131f7d0e5b02982f4696e7d1db781f45b17f8b28f17da5fe5cc3b0a4480c7a0
+  data.tar.gz: f700d3d65a3fc368e73315c436a7f8d2afb5244cd04b4b0be5618efbc738d26f
 SHA512:
-  metadata.gz: cbf194184d5d16439031b3802f5fc7b05b7f22b24a2075cac2d03a5e6869160f5332ea6cc4d83d3a580169db7405266435e5f9b7f4f1b42befd334a93a470f53
-  data.tar.gz: ec740ece535648156d103872cb0362347b6b2f2823d425aa0b94134f336a32355c807f767d05a673f173670fb1efd572c42240542b48b44f0ab5dc8b23ed63cc
+  metadata.gz: 7dc926b3cf2fb69f5dfa4644d10c47e88a39e74f3359be2572a4ea6ea46ad216a5c0447959b0e1596f0ee6ae67190140f46acc53afa332a508e63f275440bdad
+  data.tar.gz: 4d9f3fba2b94d24ef0db3d5b24b35b30d6c058acc46ac20107d37c1a507f804dac7d47b3a38556f02b16ac229ce9b2a4140e73216152c9e56ae7189a5c71bc00

data/.claude/skills/plutonium/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: plutonium
-description: Use BEFORE starting any Plutonium work — new app, new feature, or first edit in an unfamiliar area. Routes you to the right skill and bootstraps greenfield work.
+description: 'Use BEFORE starting any Plutonium work: new app, new feature, or first edit in an unfamiliar area. Routes you to the right skill and bootstraps greenfield work.'
 ---
 
-# Plutonium — Router & Bootstrapper
+# Plutonium: Router & Bootstrapper
 
 Entry point for all Plutonium work. Does three things:
 
@@ -14,57 +14,57 @@ Entry point for all Plutonium work. Does three things:
 ## 🚨 Critical (read first)
 
 - **Plutonium is generator-driven.** Almost every file you'd hand-write has a `pu:*` generator. Hand-written files drift from conventions and break future generator runs.
-- **For greenfield** (new app, substantial new feature, first resource in a new domain) — load the **bootstrap bundle** below before writing code.
-- **For targeted edits** — use the **router table** to jump to the right skill.
-- **For anything touching tenant scoping** — load `plutonium-tenancy`. Don't reach for `where(organization: ...)` in a policy; fix the model instead.
+- **For greenfield** (new app, substantial new feature, first resource in a new domain), load the **bootstrap bundle** below before writing code.
+- **For targeted edits**: use the **router table** to jump to the right skill.
+- **For anything touching tenant scoping**: load `plutonium-tenancy`. Don't reach for `where(organization: ...)` in a policy; fix the model instead.
 - **Unattended execution:** always pass `--dest=`, `--force` (when re-running meta-generators), `--auth=`, `--skip-bundle`, `--quiet` so generators don't block on prompts. See [Unattended execution](#unattended-execution).
-- **Inspect before you act.** Every targeted skill now opens with a CHECK gate — read the relevant files yourself before scaffolding or editing. Don't ask the user to describe their app when you can read it.
+- **Inspect before you act.** Every targeted skill now opens with a CHECK gate: read the relevant files yourself before scaffolding or editing. Don't ask the user to describe their app when you can read it.
 
-## The mental model (read once — it decides what you should write)
+## The mental model (read once: it decides what you should write)
 
-Plutonium applies Rails' bargain — follow the convention and the framework carries you; reach for an escape hatch when you need one — to the layer **above CRUD**: auth, authorization, multi-tenancy, admin UI, business operations. Four consequences change what you should actually type.
+Plutonium applies Rails' bargain (follow the convention and the framework carries you; reach for an escape hatch when you need one) to the layer **above CRUD**: auth, authorization, multi-tenancy, admin UI, business operations. Four consequences change what you should actually type.
 
 ### 1. Everything is derived from something you already declared
 
-Not "defaults someone picked for you" — **computed from existing declarations**:
+Not "defaults someone picked for you": **computed from existing declarations**:
 
 | Derived | From |
 |---|---|
 | Field types, required markers, select choices | model columns, associations, attachments, enums, **and validations** (`presence: true` → required; `inclusion:` → select choices) |
-| A collection's preloads (index, kanban, export) | the policy's permitted field set — there is **no `includes` list to write or maintain** |
-| Tenant scope | your associations — direct `belongs_to`, then `has_one`/`has_one :through`, then reverse `has_many` |
+| A collection's preloads (index, kanban, export) | the policy's permitted field set; there is **no `includes` list to write or maintain** |
+| Tenant scope | your associations: direct `belongs_to`, then `has_one`/`has_one :through`, then reverse `has_many` |
 | Action type (record / bulk / resource) | whether the interaction declares `:resource`, `:resources`, or neither |
 | An association input's typeahead | the **target resource's own `search` block** |
 | CRUD, nested and action routes | one `register_resource` line |
 
-⇒ **Declare only what differs.** A `field :title` matching the detected type is dead code — and one more line to fall out of step when the column changes. This is the single most common way generated-looking code goes wrong.
+⇒ **Declare only what differs.** A `field :title` matching the detected type is dead code, and one more line to fall out of step when the column changes. This is the single most common way generated-looking code goes wrong.
 
 ### 2. Definition and policy answer different questions
 
 - **Definition** = *how* a field renders.
 - **Policy** = *whether it appears at all*.
 
-"Only admins see this field" is `permitted_attributes_for_*`. Never a definition declaration, and never a `condition:` (that only hides UI — the route stays live).
+"Only admins see this field" is `permitted_attributes_for_*`. Never a definition declaration, and never a `condition:` (that only hides UI; the route stays live).
 
 ### 3. Overrides are plain Ruby inheritance
 
-`AdminPortal::PostDefinition < ::PostDefinition`, and the same for policies and controllers. App-level default, portal-level subclass. No registry of overrides, no precedence DSL, no merge semantics — so "why does this field show here but not there" is always readable as a class hierarchy.
+`AdminPortal::PostDefinition < ::PostDefinition`, and the same for policies and controllers. App-level default, portal-level subclass. No registry of overrides, no precedence DSL, no merge semantics, so "why does this field show here but not there" is always readable as a class hierarchy.
 
 ### 4. Climb the escape-hatch ladder only as far as the problem requires
 
-1. **Change an option** — `input :content, as: :markdown`
-2. **Render inline** — `display :priority, as: :phlexi_render, with: ->(value, attrs) do … end`
-3. **Write a component** — a *field* component (subclasses the Phlexi base) plugs into `as:`; anything with its own constructor goes through a block (`display :card do |field| … end`)
-4. **Implement a hook** — controller hooks instead of reopening `create`/`update`; page `render_before_*` / `render_after_*` instead of `view_template`
-5. **Replace the page** — `view_template` on the nested class, or an ERB view at the controller path (ERB wins when both exist)
+1. **Change an option**: `input :content, as: :markdown`
+2. **Render inline**: `display :priority do |f| … end` (a block, `instance_exec`ed in Phlex, emits markup directly and gives you `f.object`)
+3. **Write a component**: a *field* component (subclasses the Phlexi base) plugs into `as:`; anything with its own constructor goes through a block (`display :card do |field| … end`)
+4. **Implement a hook**: controller hooks instead of reopening `create`/`update`; page `render_before_*` / `render_after_*` instead of `view_template`
+5. **Replace the page**: `view_template` on the nested class, or an ERB view at the controller path (ERB wins when both exist)
 
 Reaching for rung 5 on a rung-1 problem is how you end up owning breadcrumbs, the header and turbo frame wiring you never meant to touch.
 
 **Underneath all of it, it stays Rails.** Models are plain ActiveRecord, controllers inherit from Rails controllers, views resolve through Rails view paths. A Plutonium resource and a hand-written controller coexist in one app.
 
-## ✅ Orient before you route (CHECK — read the app, don't assume)
+## ✅ Orient before you route (CHECK: read the app, don't assume)
 
-A one-line request rarely says whether this is a new app, a half-built one, or a multi-tenant one — and those change which path you take. Spend 30 seconds reading the app **before** loading a bundle or running anything:
+A one-line request rarely says whether this is a new app, a half-built one, or a multi-tenant one, and those change which path you take. Spend 30 seconds reading the app **before** loading a bundle or running anything:
 
 | Read | Tells you |
 |---|---|
@@ -80,15 +80,16 @@ This is the global "look before you leap"; each targeted skill carries its own A
 | Skill | Covers |
 |---|---|
 | **[[plutonium-app]]** | Installation, packages (feature + portal), portal engines, mounting, `register_resource` (including singular and custom routes), `pu:res:conn` |
-| **[[plutonium-resource]]** | The resource itself — `pu:res:scaffold`, field types, model layer (`Plutonium::Resource::Record`, `has_cents`, SGID, routing), definition layer (fields/inputs/displays/columns, search/filters/scopes/sorting, custom actions, bulk actions, index views, page customization) |
+| **[[plutonium-resource]]** | The resource itself: `pu:res:scaffold`, field types, model layer (`Plutonium::Resource::Record`, `has_cents`, SGID, routing), definition layer (fields/inputs/displays/columns, search/filters/scopes/sorting, custom actions, bulk actions, index views, page customization) |
 | **[[plutonium-behavior]]** | Controllers (hooks, key methods, presentation), policies (action methods, `permitted_attributes_for_*`, `permitted_associations`), interactions (structure, outcomes, chaining, URL generation) |
-| **[[plutonium-async-interactions]]** | Async interactions — `async`, the Run STI model, failure policies (`halt`/`continue`/`transactional`), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), scheduling `ReapJob` |
+| **[[plutonium-async-interactions]]** | Async interactions: `async`, the Run STI model, failure policies (`halt`/`continue`/`transactional`), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), scheduling `ReapJob` |
 | **[[plutonium-ui]]** | Page classes, forms, displays, tables, custom Phlex components, layouts, modals & tabs, Tailwind config, Stimulus, design tokens, `.pu-*` classes, Phlexi themes |
-| **[[plutonium-kanban]]** | `kanban do…end` DSL in a Definition — columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy, quick-add, static vs dynamic boards |
+| **[[plutonium-kanban]]** | `kanban do…end` DSL in a Definition, columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy, quick-add, static vs dynamic boards |
+| **[[plutonium-dashboard]]** | Dashboards, `Plutonium::Dashboard::Base`, `metric` / `chart` / `card`, `register_dashboard`, lazy turbo-frame cards, `refresh`, `condition:`, `authorize?`, `pu:dashboard` |
 | **[[plutonium-auth]]** | Rodauth install, account types (basic / admin / SaaS), profile resource, security section |
 | **[[plutonium-tenancy]]** | Entity scoping (`associated_with`, `default_relation_scope`, three model shapes), nested resources, invites |
 | **[[plutonium-testing]]** | `pu:test:install`, `pu:test:scaffold`, `ResourceCrud`/`ResourcePolicy`/`ResourceDefinition`/`ResourceModel`/`NestedResource`/`PortalAccess`/`ResourceInteraction`, `AuthHelpers` |
-| **[[plutonium-wizard]]** | Multi-step flows — the wizard DSL (`step`/`review`/`using:`/`condition:`, per-step `on_submit`/`persist`/`on_rollback`, `execute`), anchoring & resume, one-time wizards + gate, registration (`wizard` macro + `register_wizard`), storage/config + SweepJob |
+| **[[plutonium-wizard]]** | Multi-step flows: the wizard DSL (`step`/`review`/`using:`/`condition:`, per-step `on_submit`/`persist`/`on_rollback`, `execute`), anchoring & resume, one-time wizards + gate, registration (`wizard` macro + `register_wizard`), storage/config + SweepJob |
 
 ## Greenfield bootstrap bundle
 
@@ -96,10 +97,10 @@ Triggers: installing Plutonium, building a new app, adding the first resource in
 
 **Load these before writing code:**
 
-1. **`plutonium-app`** — install, portals, packages, routes.
-2. **`plutonium-resource`** — scaffold, model, definition (the bulk of the work).
-3. **`plutonium-behavior`** — controllers, policies, interactions.
-4. **`plutonium-tenancy`** — only if multi-tenant; load before declaring entity scoping.
+1. **`plutonium-app`**: install, portals, packages, routes.
+2. **`plutonium-resource`**: scaffold, model, definition (the bulk of the work).
+3. **`plutonium-behavior`**: controllers, policies, interactions.
+4. **`plutonium-tenancy`**: only if multi-tenant; load before declaring entity scoping.
 
 Add when relevant:
 - **`plutonium-auth`** for login / accounts / profile.
@@ -113,7 +114,7 @@ Add when relevant:
 | Install Plutonium, create a portal or package, mount engines, register routes (incl. singular / custom routes) | **[[plutonium-app]]** |
 | Run `pu:res:scaffold`, pick field types, set scaffold options | **[[plutonium-resource]]** |
 | Edit a model, add associations, use `has_cents`, override `to_param` / `to_label` | **[[plutonium-resource]]** |
-| Edit a definition — fields, inputs, displays, columns, search, filters, scopes, custom actions, bulk actions, index views, modal/slideover, page titles | **[[plutonium-resource]]** |
+| Edit a definition, fields, inputs, displays, columns, search, filters, scopes, custom actions, bulk actions, index views, modal/slideover, page titles | **[[plutonium-resource]]** |
 | Override a controller action, hook, redirect, or `resource_params` | **[[plutonium-behavior]]** |
 | Write `relation_scope`, `permitted_attributes_for_*`, `permitted_associations`, action methods, or any policy override | **[[plutonium-behavior]]** (+ **[[plutonium-tenancy]]** if scoping) |
 | Write an interaction class for business logic | **[[plutonium-behavior]]** |
@@ -121,23 +122,24 @@ Add when relevant:
 | Scope a model to a tenant, write `associated_with`, set portal entity strategy | **[[plutonium-tenancy]]** |
 | Configure parent/child nested routes, custom parent resolution | **[[plutonium-tenancy]]** |
 | Set up user invitations or entity membership | **[[plutonium-tenancy]]** |
-| Build or customize a kanban board view — `kanban do…end`, columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy | **[[plutonium-kanban]]** |
+| Build or customize a kanban board view, `kanban do…end`, columns, `card_fields`, `position_on`, `realtime`, column actions, `kanban_move?` policy | **[[plutonium-kanban]]** |
+| Build a dashboard, KPI overview or chart page, `pu:dashboard`, `metric` / `chart` / `card`, `register_dashboard`, refresh, per-card conditions | **[[plutonium-dashboard]]** |
 | Build a custom page (override `ShowPage`/`IndexPage`/`NewPage`/`EditPage`), custom form, custom display, custom table, custom Phlex component | **[[plutonium-ui]]** |
 | Configure Tailwind, register Stimulus controllers, edit design tokens, theme forms/displays/tables, write a custom layout | **[[plutonium-ui]]** |
 | Install Rodauth, set up accounts, configure login flow, add the profile resource | **[[plutonium-auth]]** |
 | Write tests for a resource, run `pu:test:scaffold`, include `Plutonium::Testing::*` concerns | **[[plutonium-testing]]** |
-| Build a multi-step flow — onboarding, checkout, branching create — register a `wizard` / `register_wizard`, gate a one-time wizard | **[[plutonium-wizard]]** |
+| Build a multi-step flow, onboarding, checkout, branching create, register a `wizard` / `register_wizard`, gate a one-time wizard | **[[plutonium-wizard]]** |
 
 ## Resource architecture at a glance
 
-A **resource** is four cooperating layers — Plutonium auto-fills defaults from the model, so you only declare overrides:
+A **resource** is four cooperating layers; Plutonium auto-fills defaults from the model, so you only declare overrides:
 
 | Layer | File | Purpose |
 |---|---|---|
 | **Model** | `app/models/post.rb` | Data, validations, associations |
-| **Definition** | `app/definitions/post_definition.rb` | UI — fields, filters, actions |
-| **Policy** | `app/policies/post_policy.rb` | Authorization — who, what |
-| **Controller** | `app/controllers/posts_controller.rb` | Request handling (rarely edited — use hooks) |
+| **Definition** | `app/definitions/post_definition.rb` | UI, fields, filters, actions |
+| **Policy** | `app/policies/post_policy.rb` | Authorization: who, what |
+| **Controller** | `app/controllers/posts_controller.rb` | Request handling (rarely edited; use hooks) |
 
 Plus one optional fifth layer:
 
@@ -169,6 +171,7 @@ Every Plutonium generator is discoverable via `rails g pu:<tab>`. Always pass `-
 | `pu:eject:shell` | Eject topbar/sidebar partials | `plutonium-ui` |
 | `pu:test:install` | Install `Plutonium::Testing` scaffolding | `plutonium-testing` |
 | `pu:test:scaffold NAME --portals=...` | Scaffold integration tests | `plutonium-testing` |
+| `pu:dashboard NAME --dest=PORTAL [--at=/]` | Dashboard class + `register_dashboard` route | `plutonium-dashboard` |
 | `pu:skills:sync` | Sync Plutonium Claude skills into the project | (this skill) |
 
 ## Unattended execution
@@ -188,8 +191,8 @@ Meta-generators (`pu:saas:setup`) propagate flags to the generators they chain.
 ## Workflow summary
 
 1. **Load the bootstrap bundle** (or the targeted skill from the router table).
-2. **Generate** — `rails g pu:res:scaffold Model field:type ... --dest=main_app`.
-3. **Migrate** — `rails db:prepare`.
-4. **Connect** — `rails g pu:res:conn Model --dest=portal_name`.
-5. **Customize** — edit definition / policy as needed.
-6. **Verify** — hit the route in the browser.
+2. **Generate**: `rails g pu:res:scaffold Model field:type ... --dest=main_app`.
+3. **Migrate**: `rails db:prepare`.
+4. **Connect**: `rails g pu:res:conn Model --dest=portal_name`.
+5. **Customize**: edit definition / policy as needed.
+6. **Verify**: hit the route in the browser.

data/.claude/skills/plutonium-app/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: plutonium-app
-description: Use BEFORE installing Plutonium, creating a portal or feature package, mounting an engine, or registering resources/routes. Covers initial setup, the package system, portal engines, route registration (including singular and custom routes), and resource-to-portal wiring.
+description: 'Use BEFORE installing Plutonium, creating a portal or feature package, mounting an engine, or registering resources/routes. Covers initial setup, the package system, portal engines, route registration (including singular and custom routes), and resource-to-portal wiring.'
 ---
 
-# Plutonium App — Installation, Packages, Portals, Routes
+# Plutonium App: Installation, Packages, Portals, Routes
 
 How a Plutonium app is assembled: the install bootstrap, the package system (feature vs portal), portal engines, and the routing surface that exposes resources to the web.
 
@@ -15,54 +15,54 @@ For the resources themselves (model + definition + scaffold options), see [[plut
 - **Existing app → `base.rb`. New app → `plutonium.rb`.** The `plutonium.rb` template re-runs full bootstrap (dotenv, annotate, solid_*, asset config) and creates generic "initial commit" commits that clobber history. For any pre-existing app use `base.rb`.
 - **Pass `--dest`, `--auth`, `--force`, `--skip-bundle`** etc. for unattended runs so generators don't block on prompts.
 - **Feature vs portal is a hard split.** Feature packages hold models/policies/definitions/interactions. Portal packages hold controllers/views/routes/auth. Don't mix.
-- **Package classes are auto-namespaced** — `packages/blogging/app/models/blogging/post.rb` → `Blogging::Post`. Don't fight it.
-- **Always connect resources with `pu:res:conn`** — until connected, a resource has no portal routes and is invisible.
-- **For custom routes on a registered resource, pass `as:`** — otherwise `resource_url_for` can't build URLs.
+- **Package classes are auto-namespaced**: `packages/blogging/app/models/blogging/post.rb` → `Blogging::Post`. Don't fight it.
+- **Always connect resources with `pu:res:conn`**: until connected, a resource has no portal routes and is invisible.
+- **For custom routes on a registered resource, pass `as:`**: otherwise `resource_url_for` can't build URLs.
 
 ---
 
-## 🛑 Before you install or scaffold structure: confirm the shape (ASK — don't infer)
+## 🛑 Before you install or scaffold structure: confirm the shape (ASK: don't infer)
 
-"Set up Plutonium" / "make an admin area" / "create a billing package" each hide a high-blast-radius decision. Get one wrong and you **clobber a year of git history**, build the wrong kind of package, or ship a portal nobody can log into. Resolve each — confirming by inspection (next section), not assumption:
+"Set up Plutonium" / "make an admin area" / "create a billing package" each hide a high-blast-radius decision. Get one wrong and you **clobber a year of git history**, build the wrong kind of package, or ship a portal nobody can log into. Resolve each, confirming by inspection (next section), not assumption:
 
-1. **Fresh app or existing one?** Existing ⇒ `bundle add plutonium` + `pu:core:install` (the `base.rb` path). **NEVER the `plutonium.rb` fresh-app template on an existing app** — it re-bootstraps (dotenv/annotate/solid_*/assets) and drops "initial commit" commits that clobber history. This is the single most dangerous mistake in this skill — confirm it's greenfield *before* reaching for `plutonium.rb`.
-2. **Feature package or portal package?** Business logic (models/policies/definitions/interactions) ⇒ `pu:pkg:package` (feature, no UI). A web surface (controllers/views/routes/auth) ⇒ `pu:pkg:portal`. Hard split — "billing" is a *feature*; "admin area" is a *portal*. A feature package is invisible until its resources are `pu:res:conn`'d into a portal.
-3. **Auth per portal.** `--auth=<account>` / `--public` / `--byo` / `--scope=<Entity>` (multi-tenant). Unguessable from "admin area" — decide, don't default silently.
-4. **Don't stop half-wired.** A resource reaches the browser only after: scaffold → migrate → `pu:res:conn --dest=portal` → portal engine `mount`ed in `config/routes.rb` → registered (conn does the last). Name the whole chain before you start.
+1. **Fresh app or existing one?** Existing ⇒ `bundle add plutonium` + `pu:core:install` (the `base.rb` path). **NEVER the `plutonium.rb` fresh-app template on an existing app**: it re-bootstraps (dotenv/annotate/solid_*/assets) and drops "initial commit" commits that clobber history. This is the single most dangerous mistake in this skill; confirm it's greenfield *before* reaching for `plutonium.rb`.
+2. **Feature package or portal package?** Business logic (models/policies/definitions/interactions) ⇒ `pu:pkg:package` (feature, no UI). A web surface (controllers/views/routes/auth) ⇒ `pu:pkg:portal`. Hard split: "billing" is a *feature*; "admin area" is a *portal*. A feature package is invisible until its resources are `pu:res:conn`'d into a portal.
+3. **Auth per portal.** `--auth=<account>` / `--public` / `--byo` / `--scope=<Entity>` (multi-tenant). Unguessable from "admin area"; decide, don't default silently.
+4. **Don't stop half-wired.** A resource reaches the browser only after: scaffold → migrate → `pu:res:conn --dest=portal` → registered in the portal's routes (conn does this) → portal engine mounted (`pu:pkg:portal` already did this). Name the whole chain before you start.
 
-**Never ship a guessed schema, portal name, or auth flag as applied commands** — read them off the app first; fall back to `AskUserQuestion` only for genuine product choices (separate staff accounts vs shared, which payment backend). The decisions compound: *existing app ⇒ base.rb path*; *feature package ⇒ needs a portal to be visible*; *new portal ⇒ pick auth + mount it*.
+**Never ship a guessed schema, portal name, or auth flag as applied commands**; read them off the app first; fall back to `AskUserQuestion` only for genuine product choices (separate staff accounts vs shared, which payment backend). The decisions compound: *existing app ⇒ base.rb path*; *feature package ⇒ needs a portal to be visible*; *new portal ⇒ pick auth + mount it*.
 
-## ✅ Before you run a generator: verify the ground truth (CHECK — read it, don't ask for it)
+## ✅ Before you run a generator: verify the ground truth (CHECK: read it, don't ask for it)
 
-You have file access — **inspect**; don't ask the user to describe their app.
+You have file access, **inspect**; don't ask the user to describe their app.
 
 | Check | How | Why it matters |
 |---|---|---|
-| Greenfield vs existing | `git log --oneline \| head`; is there a populated `Gemfile`/`app/`? | An existing app must use the `base.rb` path — **never** `plutonium.rb` |
+| Greenfield vs existing | `git log --oneline \| head`; is there a populated `Gemfile`/`app/`? | An existing app must use the `base.rb` path, **never** `plutonium.rb` |
 | Plutonium already installed | grep `Gemfile` for `plutonium`; `ls config/packages.rb app/controllers/resource_controller.rb` | Avoid re-installing / double bootstrap |
-| Package/portal already exists | `ls packages/<name>` | Don't duplicate — connect to / extend the existing one |
+| Package/portal already exists | `ls packages/<name>` | Don't duplicate; connect to / extend the existing one |
 | Existing auth | grep `Gemfile`/`app/models` for `rodauth`/`devise`/`has_secure_password` | Drives `--auth` vs `--byo` |
-| Portal engine mounted | grep `config/routes.rb` for `mount <Portal>::Engine` | An unmounted portal 404s |
+| Portal engine mounted | grep `packages/<portal>/config/routes.rb` for `mount <Portal>::Engine` | `pu:pkg:portal` writes the mount there. Don't add a second one to `config/routes.rb` (duplicate route name error) |
 | Resource registered | grep the portal's `config/routes.rb` for `register_resource ::<X>` | Unregistered ⇒ no URLs (`resource_url_for` fails) |
 | Migrations applied | `rails db:migrate:status` before `pu:res:conn` | `conn` seeds the policy from columns |
 
 Inspect with your own tools **before** running any generator.
 
-## 🛠 Use the generator — pick the right install path
+## 🛠 Use the generator: pick the right install path
 
 Never hand-write base controllers, engine files, layouts, or route registration. Pass `--dest`/`--auth`/`--force`/`--skip-bundle` for unattended runs.
 
 | Task | Generator | Verify first |
 |---|---|---|
-| Install — **existing** app | `bundle add plutonium` + `pu:core:install` | It's an existing app (use `base.rb`, **not** `plutonium.rb`) |
-| Install — **fresh** app | `rails new … -m …/plutonium.rb` | Brand-new app **only** |
+| Install, **existing** app | `bundle add plutonium` + `pu:core:install` | It's an existing app (use `base.rb`, **not** `plutonium.rb`) |
+| Install, **fresh** app | `rails new … -m …/plutonium.rb` | Brand-new app **only** |
 | Feature package | `pu:pkg:package <name>` | Not already present |
-| Portal package | `pu:pkg:portal <name> --auth=…/--public/--byo/--scope=…` | Auth strategy decided; then `mount` the engine by hand |
+| Portal package | `pu:pkg:portal <name> --auth=…/--public/--byo/--scope=…` | Auth strategy decided. The generator also mounts the engine (see Mounting) |
 | Connect a resource | `pu:res:conn <Res> --dest=portal` | Migrated; target portal exists |
 
 ---
 
-# Part 1 — Installation
+# Part 1: Installation
 
 ## Fresh Rails app (recommended)
 
@@ -78,11 +78,11 @@ Configures Rails + Propshaft + esbuild + TailwindCSS + Plutonium in one shot.
 ⚠️ Use `base.rb`, **not** `plutonium.rb`.
 
 ```bash
-# Option 1 — template
+# Option 1: template
 bin/rails app:template \
   LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
 
-# Option 2 — manual
+# Option 2: manual
 # Add `gem "plutonium"` to Gemfile, then:
 bundle install
 rails generate pu:core:install
@@ -108,10 +108,7 @@ rails db:prepare
 # 5. Connect resource to portal
 rails generate pu:res:conn Post --dest=admin_portal
 
-# 6. Mount portal in config/routes.rb
-#    mount AdminPortal::Engine, at: "/admin"
-
-# 7. Start
+# 6. Start (step 3 already mounted the portal at /admin)
 rails server
 ```
 
@@ -121,10 +118,10 @@ rails server
 app/
 ├── controllers/
 │   ├── plutonium_controller.rb       # non-resource base
-│   └── resource_controller.rb        # CRUD base — see plutonium-behavior
+│   └── resource_controller.rb        # CRUD base; see plutonium-behavior
 ├── definitions/resource_definition.rb
 ├── interactions/resource_interaction.rb
-├── models/resource_record.rb         # abstract model — includes Plutonium::Resource::Record
+├── models/resource_record.rb         # abstract model that includes Plutonium::Resource::Record
 ├── policies/resource_policy.rb
 └── views/layouts/resource.html.erb
 
@@ -174,7 +171,7 @@ end
 
 ---
 
-# Part 2 — The Package System
+# Part 2: The Package System
 
 Two kinds, hard split:
 
@@ -263,21 +260,31 @@ end
 
 This is loaded from `config/application.rb`. Migrations from all packages are picked up by `rails db:migrate` automatically.
 
+## Locale files
+
+Packages and portals are Rails engines, so `packages/<name>/config/locales/*.yml` loads automatically, ahead of the app's own `config/locales` (app wins, then packages, then the gem's defaults). Both generators scaffold `config/locales/en.yml`.
+
+- Feature package: model/attribute names (`activerecord.models`, `activerecord.attributes`) and field text (`plutonium.fields.<model>.<attr>.{placeholder,hint,description}`).
+- Portal: portal-specific wording under `plutonium.portals.<portal_namespace>.…` (same tree as the global keys: `fields`, `actions`, `scopes`, `filters`, `kanban_columns`, `values`). Wins over the global key only inside that portal.
+- Any of Plutonium's own strings (`plutonium.*` in the gem's `config/locales/en/*.yml`) can be overridden from either place. Pagination text comes from Pagy's dictionaries instead.
+
+Switch locale with a normal Rails `around_action` in the portal's controller concern; Plutonium reads `I18n.locale` and never sets it. See `docs/reference/i18n.md`.
+
 ## When to use which
 
-**Feature packages** — domain logic that:
+**Feature packages** are domain logic that:
 - Could be reused across multiple portals (admin and customer both edit `Blogging::Post`)
 - Has no inherent UI / auth (it's just behavior)
 - You want to keep isolated from other domains (`billing` should not depend on `blogging`)
 
-**Portal packages** — user-facing surfaces that:
+**Portal packages** are user-facing surfaces that:
 - Have a specific auth flow (admin vs customer vs public)
 - Render different views of the same underlying resources
 - Need different policies / definitions per audience
 
 ---
 
-# Part 3 — Portal Engines
+# Part 3: Portal Engines
 
 A portal is a Rails engine mixing in `Plutonium::Portal::Engine`. It defines its own routes, controller concern, and (optionally) entity scoping.
 
@@ -292,7 +299,7 @@ rails g pu:pkg:portal <name>
 | Option | Description |
 |---|---|
 | `--auth=NAME` | Rodauth account to use (e.g. `--auth=user`) |
-| `--public` | Public access — no auth |
+| `--public` | Public access, no auth |
 | `--byo` | Bring your own auth |
 | `--scope=CLASS` | Entity class for multi-tenancy (e.g. `--scope=Organization`) |
 
@@ -323,7 +330,9 @@ end
 
 ## Controller concern (auth)
 
-Every portal has a `Concerns::Controller` mixed into its `ResourceController`. The generator wires this up; you customize it for auth / before_action hooks.
+Every portal has a `Concerns::Controller`, included by both its `ResourceController` (resource pages) and its `PlutoniumController` (dashboard and other non-resource pages). The generator wires this up; you customize it for auth / before_action hooks.
+
+Portal-wide helpers the layout calls belong here, declared with `helper_method`, so they work on the dashboard as well as resource pages. Defining one on a single resource controller (or on the app's `::ResourceController`) leaves the dashboard without it. The common case is `profile_url`: `Plutonium::Auth::Rodauth` defines it as `nil`, and the avatar menu only shows a Profile link when it is truthy. `pu:profile:conn --dest=<portal>` writes the override into this concern; it reads `current_user.profile`, the `has_one :profile` association that `pu:profile:install` adds (see [[plutonium-auth]]). A plain `pu:res:conn --singular` registers the route but does not define `profile_url`. When testing the link, request both the portal root and a resource page.
 
 ### Rodauth
 
@@ -361,19 +370,62 @@ end
 
 ## Mounting
 
+`pu:pkg:portal` writes the mount at the bottom of the portal's own `packages/<name>_portal/config/routes.rb`, at `/<name>`, wrapped in an auth constraint when `--auth` is given:
+
 ```ruby
-# config/routes.rb
+# packages/admin_portal/config/routes.rb (after the engine's routes.draw block)
 Rails.application.routes.draw do
-  # Authenticated mount
   constraints Rodauth::Rails.authenticate(:user) do
     mount AdminPortal::Engine, at: "/admin"
   end
+end
+```
+
+To change the path, edit `at:` in place. Don't mount the engine again in `config/routes.rb`: the second `mount` reuses the route name (`admin_portal`) and Rails raises `ArgumentError: Invalid route name, already in use`.
+
+Route order matters: the app's `config/routes.rb` is drawn first, then each package's routes file, then gem engines (Active Storage, Turbo).
+
+### Mounting a portal at `/`
+
+Two things change when a portal is mounted at `"/"`.
+
+**Drop the `Rodauth::Rails.authenticate` constraint and authenticate in the controller concern instead.** The constraint does not fail the match for an anonymous visitor; it calls `rodauth.require_account`, which redirects to login. A constrained mount at `/` matches every path the app's own routes did not claim, so it redirects anonymous requests meant for routes drawn after it (other portals, Active Storage) and turns unknown URLs into login redirects.
+
+```ruby
+# packages/desk_portal/config/routes.rb
+Rails.application.routes.draw do
+  mount DeskPortal::Engine, at: "/"
+end
+
+# packages/desk_portal/app/controllers/desk_portal/concerns/controller.rb
+module DeskPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      include Plutonium::Auth::Rodauth(:user)
+      # add concerns above.
+
+      included do
+        before_action { rodauth.require_account }
+      end
+    end
+  end
+end
+```
 
-  # Unconstrained (portal handles its own auth)
-  mount PublicPortal::Engine, at: "/public"
+**Move the engine's root off `/` but keep the name.** The app's `root` is drawn first, so the generated `root to: "dashboard#index"` is unreachable and the portal's `root_path` points at the app's home page. Plutonium's header, icon rail, breadcrumbs and wizard exits all link to `root_path`, so the portal still needs a route named `root`:
+
+```ruby
+DeskPortal::Engine.routes.draw do
+  get "dashboard", to: "dashboard#index", as: :root
+  register_resource ::Comment
+  # register resources above.
 end
 ```
 
+The same applies to `register_dashboard ..., at: "/"`. Confirm with `Rails.application.routes.recognize_path("/")` (still the app's home) and `recognize_path("/dashboard")`.
+
 ## Controller hierarchy
 
 Portal controllers inherit from the feature-package controller if one exists, OR from the portal's `ResourceController` otherwise.
@@ -402,13 +454,13 @@ end
 ## Per-portal overrides
 
 ```ruby
-# Definition — how fields render (NOT whether they appear)
+# Definition: how fields render (NOT whether they appear)
 class AdminPortal::PostDefinition < ::PostDefinition
   scope :pending_review
   input :internal_notes, hint: "Not shown to the author"
 end
 
-# Policy — whether a field appears at all
+# Policy: whether a field appears at all
 class AdminPortal::PostPolicy < ::PostPolicy
   include AdminPortal::ResourcePolicy
   def destroy? = true
@@ -426,7 +478,7 @@ end
 
 ---
 
-# Part 4 — Routes & `register_resource`
+# Part 4: Routes & `register_resource`
 
 Portal routes live in `packages/<name>_portal/config/routes.rb`:
 
@@ -442,7 +494,7 @@ AdminPortal::Engine.routes.draw do
 end
 ```
 
-## `register_resource` — what it does
+## `register_resource`: what it does
 
 For each call, Plutonium auto-generates:
 
@@ -450,11 +502,11 @@ For each call, Plutonium auto-generates:
 - Nested routes for every registered `has_many` / `has_one` parent (prefixed `nested_`)
 - Route names that `resource_url_for` can resolve
 
-You list every resource the portal exposes. If a resource isn't registered, it has no URLs in that portal — `resource_url_for` will fail.
+You list every resource the portal exposes. If a resource isn't registered, it has no URLs in that portal, so `resource_url_for` will fail.
 
 ## Singular (singleton) resources
 
-For resources with no collection — a single per-user `Profile`, app-wide `Settings`, etc.:
+For resources with no collection, a single per-user `Profile`, app-wide `Settings`, etc.:
 
 ```ruby
 register_resource ::Profile, singular: true
@@ -475,6 +527,10 @@ Use the `--singular` flag on `pu:res:conn`:
 rails g pu:res:conn Profile --dest=customer_portal --singular
 ```
 
+## Dashboards
+
+`register_dashboard SomeDashboard, at: "overview"` mounts a `Plutonium::Dashboard::Base` subclass (metric / chart / free-form cards, each in its own lazy turbo frame) on the portal at `/dashboards/overview`; `at: "/"` (generator: `--at=/`) makes it the portal root in place of `root to: "dashboard#index"`; delete the generated `DashboardController` and view afterwards. Generate one with `rails g pu:dashboard Overview --dest=<portal>`. See [[plutonium-dashboard]].
+
 ## Custom member / collection routes
 
 ```ruby
@@ -491,9 +547,9 @@ register_resource ::Post do
 end
 ```
 
-**Always pass `as:`.** Without it, `resource_url_for(@post, action: :preview)` fails because there's no named route to look up — especially critical for nested resources.
+**Always pass `as:`.** Without it, `resource_url_for(@post, action: :preview)` fails because there's no named route to look up, which is especially critical for nested resources.
 
-For most operations with business logic, prefer **interactive actions** (definition + interaction — see [[plutonium-resource]] › Actions) over custom controller routes. The action routes are wired automatically with no `register_resource` block needed.
+For most operations with business logic, prefer **interactive actions** (definition + interaction, see [[plutonium-resource]] › Actions) over custom controller routes. The action routes are wired automatically with no `register_resource` block needed.
 
 ## Cross-package and nested URLs
 
@@ -501,7 +557,7 @@ See [[plutonium-behavior]] for full `resource_url_for` signature and [[plutonium
 
 ---
 
-# Part 5 — Connecting Resources to Portals (`pu:res:conn`)
+# Part 5: Connecting Resources to Portals (`pu:res:conn`)
 
 A resource is invisible until connected to at least one portal. The generator wires up the portal-specific controller, policy, definition, and route registration.
 
@@ -511,7 +567,7 @@ A resource is invisible until connected to at least one portal. The generator wi
 rails g pu:res:conn RESOURCE [RESOURCE...] --dest=PORTAL_NAME [--singular]
 ```
 
-Pass resources directly — avoids interactive prompts. No `--src` needed.
+Pass resources directly; this avoids interactive prompts. No `--src` needed.
 
 ## Usage
 
@@ -526,7 +582,7 @@ rails g pu:res:conn Blogging::Post Blogging::Comment --dest=admin_portal
 rails g pu:res:conn Profile --dest=customer_portal --singular
 ```
 
-**Run after migrations** — the generator reads model columns to seed the policy's `permitted_attributes_for_*`.
+**Run after migrations**: the generator reads model columns to seed the policy's `permitted_attributes_for_*`.
 
 ## What gets generated
 
@@ -546,7 +602,7 @@ register_resource ::Post
 register_resource ::Profile, singular: true   # if --singular
 ```
 
-Re-running `pu:res:conn` for the same resource is **idempotent** — already-registered entries report `identical` and are not duplicated. Insertion falls back gracefully when the conventional `# register resources above` marker is missing (uses the `routes.draw do` opening), and warns clearly if it can't find any anchor.
+Re-running `pu:res:conn` for the same resource is **idempotent**: already-registered entries report `identical` and are not duplicated. Insertion falls back gracefully when the conventional `# register resources above` marker is missing (uses the `routes.draw do` opening), and warns clearly if it can't find any anchor.
 
 ### Generated controller
 
@@ -576,7 +632,7 @@ class AdminPortal::PostPolicy < ::PostPolicy
 end
 ```
 
-Review and trim — the generator is liberal. Especially: drop `_id` fields when the form uses the association name, and add `:price` (not `:price_cents`) for `has_cents` fields.
+Review and trim: the generator is liberal. Especially: drop `_id` fields when the form uses the association name, and add `:price` (not `:price_cents`) for `has_cents` fields.
 
 ---
 
@@ -607,9 +663,9 @@ Review and trim — the generator is liberal. Especially: drop `_id` fields when
 
 ## Related skills
 
-- [[plutonium-resource]] — what a resource IS (model + definition + scaffold options)
-- [[plutonium-behavior]] — controllers, policies, interactions
-- [[plutonium-tenancy]] — entity scoping, nested resources, invites
-- [[plutonium-auth]] — Rodauth account configuration
-- [[plutonium-ui]] — layouts, page classes, custom Phlex components, assets
-- [[plutonium-testing]] — testing portals, packages, controllers
+- [[plutonium-resource]]: what a resource IS (model + definition + scaffold options)
+- [[plutonium-behavior]]: controllers, policies, interactions
+- [[plutonium-tenancy]]: entity scoping, nested resources, invites
+- [[plutonium-auth]]: Rodauth account configuration
+- [[plutonium-ui]]: layouts, page classes, custom Phlex components, assets
+- [[plutonium-testing]]: testing portals, packages, controllers