plutonium 0.64.0 → 0.66.0

data/docs/getting-started/tutorial/08-customizing-ui.md

@@ -112,39 +112,39 @@ class Blogging::PostDefinition < Blogging::ResourceDefinition
   index_page_title "Blog Posts"
   index_page_description "Manage your blog content"
 
-  show_page_title { |record| record.title }
   show_page_description "View post details"
 end
 ```
 
+These setters take a literal, or the definition's lazy `t("some.key")` to translate per request. They have no record context, so a title built from the record goes in a `page_title` override on the page class (below).
+
 The default "Posts" heading becomes your branded title and description:
 
 ![Customized index page title](/images/tutorial/08-customized-index.png)
 
-For more advanced customization, you can create custom page classes that inherit from Plutonium's page components:
+For more advanced customization, override the page class nested in the definition:
 
 ```ruby
-# packages/admin_portal/app/views/admin_portal/blogging/posts/index_page.rb
-class AdminPortal::Blogging::Posts::IndexPage < Blogging::PostDefinition::IndexPage
-  private
-
-  def page_title
-    "Blog Posts"
-  end
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  class ShowPage < ShowPage
+    private
 
-  def page_description
-    "Manage your blog content"
-  end
+    def page_title
+      object.title
+    end
 
-  # Add content after the page header
-  def render_after_page_header
-    div(class: "mb-4 p-4 bg-blue-50 rounded") do
-      p { "Custom content here" }
+    # Add content after the page header
+    def render_after_page_header
+      div(class: "pu-alert pu-alert-info", role: "status") do
+        div(class: "pu-alert-message") { t("blogging.posts.show.comment_count", count: object.comments.count) }
+      end
     end
   end
 end
 ```
 
+`pu-alert pu-alert-<success|warning|danger|info>` is the banner the flash messages use, with dark-mode colors built in. The text comes from a locale key (see [i18n](/reference/i18n#your-own-components-and-pages)).
+
 ## Custom Form Layout
 
 Control form layout using wrapper options in definitions:
@@ -171,20 +171,35 @@ end
 
 ## Theming with TailwindCSS
 
-Plutonium uses TailwindCSS 4. Customize the theme:
+Plutonium uses TailwindCSS 4. Out of the box the app serves the gem's prebuilt CSS, so first switch it to your own build:
 
-```css
-/* app/assets/stylesheets/application.css */
-@import "tailwindcss";
-@import "gem:plutonium/src/css/plutonium.css";
+```bash
+rails generate pu:core:assets
+```
+
+Brand colors are Tailwind palette colors compiled into the CSS, so change them in the generated `tailwind.config.js` through `plutoniumTailwindConfig.merge`, then rebuild:
+
+```javascript
+// tailwind.config.js
+theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
+  extend: {
+    colors: {
+      primary: { 500: '#6366f1', 600: '#4f46e5', 700: '#4338ca' },  // Indigo
+    },
+  },
+}),
+```
 
-@theme {
-  --color-primary-500: #6366f1;  /* Indigo */
-  --color-primary-600: #4f46e5;
-  --color-primary-700: #4338ca;
+Surfaces, borders, radii and shadows are `--pu-*` tokens. Override them after the Plutonium import in `app/assets/stylesheets/application.tailwind.css`, and repeat every one you change in a `.dark` block so dark mode gets its own value:
+
+```css
+:root {
+  --pu-radius-md: 0.5rem;
+  --pu-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+}
 
-  --radius-md: 0.5rem;
-  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+.dark {
+  --pu-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4);
 }
 ```
 
@@ -201,9 +216,9 @@ class StatusBadge < Plutonium::UI::Component::Base
 
   def view_template
     if @published
-      span(class: "px-2 py-1 text-xs bg-green-100 text-green-800 rounded") { "Published" }
+      span(class: "pu-badge pu-badge-success") { t("blogging.posts.status.published") }
     else
-      span(class: "px-2 py-1 text-xs bg-yellow-100 text-yellow-800 rounded") { "Draft" }
+      span(class: "pu-badge pu-badge-warning") { t("blogging.posts.status.draft") }
     end
   end
 end
@@ -224,7 +239,7 @@ class CustomLayout < Plutonium::UI::Layout::ResourceLayout
 
   # Customize body classes
   def body_attributes
-    {class: "antialiased min-h-screen bg-white dark:bg-gray-900"}
+    {class: "antialiased pu-min-h-viewport bg-[var(--pu-surface)] text-[var(--pu-text)]"}
   end
 
   # Add content before the main section

data/docs/getting-started/tutorial/index.md

@@ -60,7 +60,7 @@ Customize forms, tables, and views to match your requirements.
 If you get stuck:
 
 - Check the [Guides](/guides/) for task-oriented walkthroughs.
-- Browse the [Reference](/reference/) for full API surface — [App](/reference/app/), [Resource](/reference/resource/), [Behavior](/reference/behavior/), [UI](/reference/ui/), [Auth](/reference/auth/), [Tenancy](/reference/tenancy/), [Testing](/reference/testing/).
+- Browse the [Reference](/reference/) for full API surface: [App](/reference/app/), [Resource](/reference/resource/), [Behavior](/reference/behavior/), [UI](/reference/ui/), [Auth](/reference/auth/), [Tenancy](/reference/tenancy/), [Testing](/reference/testing/).
 - Visit [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues).
 
 [Begin Chapter 1: Project Setup →](./01-setup)

data/docs/guides/adding-resources.md

@@ -40,6 +40,8 @@ rails g pu:res:conn Post --dest=admin_portal
 
 This creates the portal-specific controller, policy, and definition, plus registers the resource in the portal's routes. Until you do this, the resource has no URL.
 
+Run it after the migration. When there is no base policy to inherit from, `pu:res:conn` seeds the policy's attribute lists from the table's columns; on an unmigrated table it logs an error and writes empty lists.
+
 For singular resources (`/profile`, `/settings`), add `--singular`:
 
 ```bash
@@ -48,7 +50,7 @@ rails g pu:res:conn Profile --dest=customer_portal --singular
 
 ### 5. Trim the generated policy
 
-The generator is liberal — it seeds `permitted_attributes_for_*` from your model columns. Open `packages/admin_portal/app/policies/admin_portal/post_policy.rb` and:
+The generator is liberal: it seeds `permitted_attributes_for_*` from your model columns. Open `packages/admin_portal/app/policies/admin_portal/post_policy.rb` and:
 
 - Drop `_id` fields when the form should use the association name (e.g. `:user`, not `:user_id`).
 - Replace `:price_cents` with `:price` if the model uses `has_cents`.
@@ -83,7 +85,7 @@ You should see:
 
 Two paths:
 
-**Migration only.** Add a new column with a standard Rails migration. Plutonium auto-detects it — appears in all CRUD pages.
+**Migration only.** Add a new column with a standard Rails migration. Plutonium auto-detects it and shows it in all CRUD pages.
 
 **Field with custom rendering.** Add the column, then declare it in the definition:
 
@@ -117,6 +119,7 @@ rails g pu:res:conn Post --dest=admin_portal
 
 ```bash
 rails g pu:res:scaffold Blogging::Post title:string --dest=blogging
+rails db:prepare
 rails g pu:res:conn Blogging::Post --dest=admin_portal
 ```
 
@@ -132,8 +135,8 @@ The `blogging/post` syntax expands to `Blogging::Post`.
 
 ## Related
 
-- [Reference › App › Generators](/reference/app/generators) — full generator catalog
-- [Reference › Resource](/reference/resource/) — model + definition + query + actions
-- [Reference › App › Portals](/reference/app/portals) — `pu:res:conn` details
-- [Creating packages](./creating-packages) — resources in feature packages
-- [Nested resources](./nested-resources) — parent/child relationships
+- [Reference › App › Generators](/reference/app/generators): full generator catalog
+- [Reference › Resource](/reference/resource/): model + definition + query + actions
+- [Reference › App › Portals](/reference/app/portals): `pu:res:conn` details
+- [Creating packages](./creating-packages): resources in feature packages
+- [Nested resources](./nested-resources): parent/child relationships

data/docs/guides/authentication.md

@@ -6,7 +6,7 @@ Add Rodauth-based authentication to your Plutonium app.
 
 Authenticated users can sign up, log in, change passwords, and reset forgotten passwords. Pages in protected portals are gated.
 
-## Quick path — basic user auth
+## Quick path: basic user auth
 
 ```bash
 # 1. Install Rodauth
@@ -22,7 +22,7 @@ rails db:prepare
 #    (when you run `pu:pkg:portal admin --auth=user`, this happens automatically)
 ```
 
-If you generated the portal with `--auth=user`, the engine is already mounted with the `Rodauth::Rails.authenticate(:user)` constraint — open `packages/admin_portal/config/routes.rb` to see it. The wiring looks like:
+If you generated the portal with `--auth=user`, the engine is already mounted with the `Rodauth::Rails.authenticate(:user)` constraint: open `packages/admin_portal/config/routes.rb` to see it. The wiring looks like:
 
 ```ruby
 # packages/admin_portal/config/routes.rb (generated)
@@ -64,13 +64,13 @@ EMAIL=admin@example.com rails rodauth:admin
 
 The task creates the account and triggers a verification email; the admin sets their own password through that flow. No password is passed on the command line.
 
-### Multi-tenant SaaS — user + entity + membership in one shot
+### Multi-tenant SaaS: user + entity + membership in one shot
 
 ```bash
 rails generate pu:saas:setup --user Customer --entity Organization
 ```
 
-⚠️ This is a **meta-generator** — it also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually. See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup).
+⚠️ This is a **meta-generator**: it also runs `pu:saas:portal`, `pu:profile:setup`, `pu:saas:welcome`, and `pu:invites:install`. Don't re-run those manually. See [Reference › Auth › Accounts › SaaS setup](/reference/auth/accounts#saas-setup).
 
 ### API-only (JWT)
 
@@ -103,7 +103,7 @@ module CustomerPortal::Concerns::Controller
 end
 ```
 
-Multiple account types — different portals use different Rodauth instances:
+Multiple account types (different portals use different Rodauth instances):
 
 ```ruby
 # Admin portal
@@ -117,40 +117,40 @@ See [Reference › App › Portals](/reference/app/portals#controller-concern-au
 
 ## Multiple portals in one browser
 
-A person can hold a session in several portals at once — signed into the admin portal and the customer portal in the same browser, with neither evicting the other. Two settings make that work, and the generators emit both:
+A person can hold a session in several portals at once (signed into the admin portal and the customer portal in the same browser, with neither evicting the other). Two settings make that work, and the generators emit both:
 
 ```ruby
-# app/rodauth/rodauth_plugin.rb — the shared base
+# app/rodauth/rodauth_plugin.rb: the shared base
 configure do
   enable :session_isolation
 end
 ```
 
 ```ruby
-# app/rodauth/admin_rodauth_plugin.rb — once per account type
+# app/rodauth/admin_rodauth_plugin.rb: once per account type
 configure do
   session_key_prefix "admin_"
   remember_cookie_key "_admin_remember"
 end
 ```
 
-Both are required. `session_key_prefix` namespaces *every* session key a configuration touches — the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup` and the rest. `session_isolation` uses that prefix to decide which entries belong to whom, and stops one configuration's login from clearing another's.
+Both are required. `session_key_prefix` namespaces *every* session key a configuration touches, the account id plus `authenticated_by`, `login_redirect`, `two_factor_auth_setup` and the rest. `session_isolation` uses that prefix to decide which entries belong to whom, and stops one configuration's login from clearing another's.
 
 ::: danger Do not also set `session_key`
-An explicit `session_key` is **not** prefixed (`convert_session_key`, `rodauth/features/base.rb:686` — only the default value passes through it). Setting both leaves the account id on a different name from every other key, so they stop rotating together. A session that holds an account id but no `authenticated_by` makes Rodauth raise on *every request* — `logged_in_via_remember_key?` calls `nil.include?` (`remember.rb:175`).
+An explicit `session_key` is **not** prefixed (`convert_session_key`, `rodauth/features/base.rb:686`, only the default value passes through it). Setting both leaves the account id on a different name from every other key, so they stop rotating together. A session that holds an account id but no `authenticated_by` makes Rodauth raise on *every request*, `logged_in_via_remember_key?` calls `nil.include?` (`remember.rb:175`).
 
 A config without a prefix at all is also not isolated: its keys are Rodauth's unprefixed defaults, indistinguishable from any other unprefixed config's, so `session_isolation` carries nothing for it.
 :::
 
 ::: details Why this is needed
-Rodauth resets the session on every login — including the `remember` feature's `load_memory` autologin — to defend against session fixation, and rodauth-rails implements that reset as a full `reset_session`.
+Rodauth resets the session on every login, including the `remember` feature's `load_memory` autologin, to defend against session fixation, and rodauth-rails implements that reset as a full `reset_session`.
 
 Without `session_isolation`, signing into one portal wipes every other portal's session. And because `RodauthApp#route` calls `load_memory` for *every* configuration on *every* request, the evicted configuration immediately autologins from its remember cookie and evicts the new one right back. The last `load_memory` call in the route block wins permanently, so the other portal can never hold a session at all.
 
 `session_isolation` carries only the *other configurations'* session entries across the reset. The session id is still rotated and application session data is still cleared, so session fixation is still defeated.
 :::
 
-Reading a raw Rodauth session key? Go through its accessor, never the literal — with a prefix set, the literal is the wrong key:
+Reading a raw Rodauth session key? Go through its accessor, never the literal: with a prefix set, the literal is the wrong key:
 
 ```ruby
 after_login do
@@ -159,9 +159,9 @@ after_login do
 end
 ```
 
-**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin and `session_key_prefix` in each account plugin — and **delete the existing `session_key "_x_session"` line** while you're there, for the reason above.
+**Upgrading an app generated before this existed:** add `enable :session_isolation` once in the base plugin and `session_key_prefix` in each account plugin, and **delete the existing `session_key "_x_session"` line** while you're there, for the reason above.
 
-Every key name changes together, so old session cookies stop matching and are ignored — the safe outcome. Keeping the old `session_key` to "preserve" logins is what produces the half-migrated session that crashes.
+Every key name changes together, so old session cookies stop matching and are ignored (the safe outcome). Keeping the old `session_key` to "preserve" logins is what produces the half-migrated session that crashes.
 
 In practice only *unremembered* sessions drop: `remember_cookie_key` is a cookie name and isn't touched by the prefix, so anyone holding a valid `_x_remember` cookie is restored by `load_memory` on their next request, which writes the new prefixed keys. Expect logouts for users who never ticked "Remember Me", not a full sign-out.
 
@@ -180,9 +180,9 @@ after_login { remember_login }
 ```
 
 ::: warning Compare the value, don't just check presence
-`param_or_nil(remember_param)` on its own is a truthiness check, and `remember_param` is shared with Rodauth's `/remember` settings page — which submits `forget` and `disable` as well as `remember`. A bare presence check means `remember=disable` would remember you. Compare against `remember_remember_param_value`, as above.
+`param_or_nil(remember_param)` on its own is a truthiness check, and `remember_param` is shared with Rodauth's `/remember` settings page, which submits `forget` and `disable` as well as `remember`. A bare presence check means `remember=disable` would remember you. Compare against `remember_remember_param_value`, as above.
 
-Plutonium's login form also passes `include_hidden: false` to `check_box`, so an unticked box sends nothing at all rather than Rails' default `"0"`. With the value comparison that's belt-and-braces rather than load-bearing (`"0" == "remember"` is already false) — but it keeps a junk param off the wire and keeps the form correct for anyone who reverts the hook to a bare truthiness check.
+Plutonium's login form also passes `include_hidden: false` to `check_box`, so an unticked box sends nothing at all rather than Rails' default `"0"`. With the value comparison that's belt-and-braces rather than load-bearing (`"0" == "remember"` is already false), but it keeps a junk param off the wire and keeps the form correct for anyone who reverts the hook to a bare truthiness check.
 :::
 
 Logged-in users can change the setting later on Rodauth's `/remember` page (Remember / Forget / Disable).
@@ -254,15 +254,15 @@ user
 
 ## Common issues
 
-- **"You need to set up Rodauth"** — run `pu:rodauth:install` first.
-- **Portal redirects to login even though you're authenticated** — the portal mount constraint references a different Rodauth account than the portal's controller concern uses. Match them up.
-- **Email confirmation never arrives in development** — Plutonium sets ActionMailer to `:test` by default. Check `tmp/letter_opener/` or your mail interceptor. In production, configure SMTP (see above).
-- **Signing into one portal signs you out of another** — or one portal can never stay signed in at all. Missing `enable :session_isolation` and/or `session_key_prefix`; see [Multiple portals in one browser](#multiple-portals-in-one-browser).
+- **"You need to set up Rodauth"**: run `pu:rodauth:install` first.
+- **Portal redirects to login even though you're authenticated**: the portal mount constraint references a different Rodauth account than the portal's controller concern uses. Match them up.
+- **Email confirmation never arrives in development**: Plutonium sets ActionMailer to `:test` by default. Check `tmp/letter_opener/` or your mail interceptor. In production, configure SMTP (see above).
+- **Signing into one portal signs you out of another**: or one portal can never stay signed in at all. Missing `enable :session_isolation` and/or `session_key_prefix`; see [Multiple portals in one browser](#multiple-portals-in-one-browser).
 
 ## Related
 
-- [Reference › Auth](/reference/auth/) — full auth surface
-- [Authorization](./authorization) — controlling who can do what AFTER login
-- [Multi-tenancy](./multi-tenancy) — entity scoping for SaaS apps
-- [User invites](./user-invites) — invitation-based onboarding
-- [User profile](./user-profile) — account-settings page
+- [Reference › Auth](/reference/auth/): full auth surface
+- [Authorization](./authorization): controlling who can do what AFTER login
+- [Multi-tenancy](./multi-tenancy): entity scoping for SaaS apps
+- [User invites](./user-invites): invitation-based onboarding
+- [User profile](./user-profile): account-settings page

data/docs/guides/authorization.md

@@ -10,9 +10,9 @@ For each resource, decide who can create / read / update / destroy / run custom
 
 Every policy controls three things:
 
-1. **Action permissions** — `create?`, `read?`, `update?`, `destroy?`, plus your custom action methods.
-2. **Attribute permissions** — `permitted_attributes_for_create`, `_for_read`, etc.
-3. **Collection scope** — `relation_scope` (which records show up in lists).
+1. **Action permissions**: `create?`, `read?`, `update?`, `destroy?`, plus your custom action methods.
+2. **Attribute permissions**: `permitted_attributes_for_create`, `_for_read`, etc.
+3. **Collection scope**: `relation_scope` (which records show up in lists).
 
 ## 🚨 Critical
 
@@ -39,7 +39,7 @@ class PostPolicy < ResourcePolicy
 end
 ```
 
-These default to `false` — without an explicit override, nobody can create or read records.
+These default to `false`, without an explicit override, nobody can create or read records.
 
 ### 3. Override derived methods only when rules differ
 
@@ -55,7 +55,7 @@ def destroy?
 end
 ```
 
-🚨 **`record` is the resource CLASS on collection routes.** `read?` backs both `show?` (called with the record) and `index?` (called with the class — there is no single record to pass). The same goes for `create?`/`new?`, `export_csv?`, `search?`, and resource-action gates. So `def read? = record.published?` raises `NoMethodError` the moment the index renders. Keep record-state rules out of these methods: filter what the list shows in `relation_scope` (step 6 below), and gate individual records in `show?` (which always receives the record). Record-action methods like `publish?` are safe — they are always evaluated against an instance.
+🚨 **`record` is the resource CLASS on collection routes.** `read?` backs both `show?` (called with the record) and `index?` (called with the class: there is no single record to pass). The same goes for `create?`/`new?`, `export_csv?`, `search?`, and resource-action gates. So `def read? = record.published?` raises `NoMethodError` the moment the index renders. Keep record-state rules out of these methods: filter what the list shows in `relation_scope` (step 6 below), and gate individual records in `show?` (which always receives the record). Record-action methods like `publish?` are safe; they are always evaluated against an instance.
 
 ### 4. Declare attribute permissions
 
@@ -69,8 +69,8 @@ def permitted_attributes_for_read
 end
 ```
 
-::: warning Index has no `record`
-`permitted_attributes_for_index` runs at collection level — `record` is `nil`. If you write a `record`-dependent `_for_read`, you MUST also declare an explicit `_for_index`. See [Reference › Behavior › Policies › Index has no record](/reference/behavior/policies#index-has-no-record).
+::: warning Index has no `record` instance
+`permitted_attributes_for_index` runs at collection level, where `record` is the resource class. `_for_index` falls back to `_for_read` (and `_for_export` to `_for_index`), so if you write a `record`-dependent `_for_read`, you MUST also declare an explicit `_for_index` that never touches `record`. See [Reference › Behavior › Policies › Index has no record](/reference/behavior/policies#index-has-no-record).
 :::
 
 ### 5. Custom action methods
@@ -87,7 +87,7 @@ end
 
 The method name matches the action name plus `?`. Undefined methods return `false`.
 
-### 6. Optionally filter the collection — `relation_scope`
+### 6. Optionally filter the collection: `relation_scope`
 
 ```ruby
 relation_scope do |relation|
@@ -95,7 +95,7 @@ relation_scope do |relation|
 end
 ```
 
-🚨 `default_relation_scope(relation)` must be called somewhere in the chain — otherwise `verify_default_relation_scope_applied!` raises at runtime. Calling it explicitly here is safest. `super` works only when the parent policy also calls it.
+🚨 `default_relation_scope(relation)` must be called somewhere in the chain, otherwise `verify_default_relation_scope_applied!` raises at runtime. Calling it explicitly here is safest. `super` works only when the parent policy also calls it.
 
 ## Common patterns
 
@@ -143,7 +143,7 @@ def update?
 end
 ```
 
-## Bulk action authorization — per record
+## Bulk action authorization: per record
 
 ```ruby
 def bulk_archive?
@@ -154,7 +154,7 @@ end
 - **Backend:** if any selected record fails, the entire request is rejected.
 - **UI:** only actions ALL selected records support are shown (intersection).
 
-Records come from `current_authorized_scope` — users can only select records they can access.
+Records come from `current_authorized_scope`; users can only select records they can access.
 
 ## Portal-specific policies
 
@@ -163,7 +163,7 @@ class PostPolicy < ResourcePolicy
   def create? = user.present?
 end
 
-# Admin — more permissive
+# Admin: more permissive
 class AdminPortal::PostPolicy < ::PostPolicy
   include AdminPortal::ResourcePolicy
 
@@ -171,7 +171,7 @@ class AdminPortal::PostPolicy < ::PostPolicy
   def permitted_attributes_for_create = %i[title content featured internal_notes]
 end
 
-# Public — read-only
+# Public: read-only
 class PublicPortal::PostPolicy < ::PostPolicy
   include PublicPortal::ResourcePolicy
   def create? = false
@@ -186,7 +186,7 @@ def permitted_associations
 end
 ```
 
-Drives the show-page tablist. Each named association must exist on the model AND be a registered Plutonium resource. See [Reference › Behavior › Policies › Association permissions](/reference/behavior/policies#association-permissions).
+Drives the show-page tablist. Each named association must exist on the model AND be a registered Plutonium resource in every portal that uses the policy; a portal that doesn't register the child raises `ArgumentError ... is not a registered resource` on its show page. To add a tab in one portal only, put it in a portal-specific policy (`rails g pu:res:conn <Resource> --dest=<portal> --policy`). See [Reference › Behavior › Policies › Association permissions](/reference/behavior/policies#association-permissions).
 
 ::: warning Not for nested forms
 `permitted_associations` is for show-page navigation tabs, NOT nested forms. Nested forms come from `nested_input :variants` in the definition. See [Reference › Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs).
@@ -194,7 +194,7 @@ Drives the show-page tablist. Each named association must exist on the model AND
 
 ## Multi-tenant scoping
 
-When the portal sets `scope_to_entity Organization`, the inherited `relation_scope` automatically filters everything to the current org — no work in the policy. To add filters on top:
+When the portal sets `scope_to_entity Organization`, the inherited `relation_scope` automatically filters everything to the current org, no work in the policy. To add filters on top:
 
 ```ruby
 relation_scope do |relation|
@@ -243,15 +243,15 @@ end
 
 ## Common issues
 
-- **Undefined custom action policy method** — the button silently disappears (undefined returns `false`). Add `def my_action?` to the policy.
-- **`record.X` crashes during index** — `record` is `nil` on index. Add an explicit `permitted_attributes_for_index` that doesn't depend on `record`.
-- **`verify_default_relation_scope_applied!` raises** — your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
-- **`super` in `relation_scope`** — works when you're extending a parent policy that itself calls `default_relation_scope`. If you're not sure (or you're inheriting from `Plutonium::Resource::Policy` directly), call `default_relation_scope(relation)` explicitly. The runtime check verifies `default_relation_scope` was hit somewhere — not that you wrote it in this class.
+- **Undefined custom action policy method**: the button silently disappears (undefined returns `false`). Add `def my_action?` to the policy.
+- **`record.X` crashes during index**: `record` is the resource class on index, not an instance. Add an explicit `permitted_attributes_for_index` that doesn't depend on `record`.
+- **`verify_default_relation_scope_applied!` raises**: your custom `relation_scope` doesn't call `default_relation_scope(relation)`. Fix by composing: `default_relation_scope(relation).where(...)`.
+- **`super` in `relation_scope`**; works when you're extending a parent policy that itself calls `default_relation_scope`. If you're not sure (or you're inheriting from `Plutonium::Resource::Policy` directly), call `default_relation_scope(relation)` explicitly. The runtime check verifies `default_relation_scope` was hit somewhere: not that you wrote it in this class.
 
 ## Related
 
-- [Reference › Behavior › Policies](/reference/behavior/policies) — full policy surface
-- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping) — `default_relation_scope`, multi-tenant patterns
-- [Authentication](./authentication) — who's the user in the first place
-- [Multi-tenancy](./multi-tenancy) — entity scoping setup
-- [Custom actions](./custom-actions) — defining the actions that need policy methods
+- [Reference › Behavior › Policies](/reference/behavior/policies): full policy surface
+- [Reference › Tenancy › Entity scoping](/reference/tenancy/entity-scoping): `default_relation_scope`, multi-tenant patterns
+- [Authentication](./authentication): who's the user in the first place
+- [Multi-tenancy](./multi-tenancy): entity scoping setup
+- [Custom actions](./custom-actions): defining the actions that need policy methods

data/docs/guides/creating-packages.md

@@ -13,7 +13,7 @@ Domain code (models, policies, definitions, interactions) lives in **feature pac
 | **Feature** | Business logic | `pu:pkg:package NAME` | `blogging`, `billing`, `inventory` |
 | **Portal** | Web interface | `pu:pkg:portal NAME` | `admin_portal`, `customer_portal`, `public_portal` |
 
-🚨 Don't mix the two. Feature packages own the **domain code** — models, interactions, policies/definitions for resources owned by that feature. Portal packages own the **web surface** — controllers, routes, auth, and portal-specific policy/definition *overrides* for resources they expose.
+🚨 Don't mix the two. Feature packages own the **domain code**: models, interactions, policies/definitions for resources owned by that feature. Portal packages own the **web surface**: controllers, routes, auth, and portal-specific policy/definition *overrides* for resources they expose.
 
 ## Feature package
 
@@ -59,12 +59,12 @@ rails g pu:pkg:portal admin --auth=user
 
 Options:
 
-- `--auth=NAME` — Rodauth account to authenticate with.
-- `--public` — public access, no auth.
-- `--byo` — bring your own auth.
-- `--scope=CLASS` — entity class for multi-tenancy.
+- `--auth=NAME`: Rodauth account to authenticate with.
+- `--public`: public access, no auth.
+- `--byo`: bring your own auth.
+- `--scope=CLASS`: entity class for multi-tenancy.
 
-The generator mounts the engine for you — at `/admin` in this case, wrapped in `constraints Rodauth::Rails.authenticate(:user)` because you passed `--auth=user`. Open `packages/admin_portal/config/routes.rb` to see the generated mount.
+The generator mounts the engine for you: at `/admin` in this case, wrapped in `constraints Rodauth::Rails.authenticate(:user)` because you passed `--auth=user`. Open `packages/admin_portal/config/routes.rb` to see the generated mount.
 
 ### 2. Connect resources
 
@@ -87,7 +87,7 @@ Every file under `app/<kind>/blogging/` resolves to `Blogging::*`:
 - `app/models/blogging/post.rb` → `Blogging::Post`
 - `app/policies/blogging/post_policy.rb` → `Blogging::PostPolicy`
 
-Each feature package gets base classes — `Blogging::ApplicationRecord`, `Blogging::ResourceRecord`, `Blogging::ResourcePolicy`, `Blogging::ResourceDefinition`, `Blogging::ResourceInteraction` — that inherit from the main app's.
+Each feature package gets base classes, `Blogging::ApplicationRecord`, `Blogging::ResourceRecord`, `Blogging::ResourcePolicy`, `Blogging::ResourceDefinition`, `Blogging::ResourceInteraction`, that inherit from the main app's.
 
 ## Cross-package references
 
@@ -129,7 +129,7 @@ packages/
 └── customer_portal/         # Portal: customer dashboard
 ```
 
-The portals expose the features. A single feature can be exposed by multiple portals — usually with different policies and definitions per portal.
+The portals expose the features. A single feature can be exposed by multiple portals, usually with different policies and definitions per portal.
 
 ## Package loading
 
@@ -147,13 +147,13 @@ Loaded from `config/application.rb`. Migrations from all packages are picked up
 ## Per-portal overrides
 
 ```ruby
-# Definition — how fields render per portal
+# Definition: how fields render per portal
 class AdminPortal::PostDefinition < ::PostDefinition
   scope :pending_review
   input :internal_notes, hint: "Not shown to the author"
 end
 
-# Policy — which fields exist, and who may act
+# Policy: which fields exist, and who may act
 #          `internal_notes` appears for admins because THIS permits it,
 #          not because the definition above mentions it.
 class AdminPortal::PostPolicy < ::PostPolicy
@@ -166,13 +166,13 @@ end
 
 ## Common issues
 
-- **Class not loading** — namespace must match the directory: `app/models/blogging/post.rb` MUST be `Blogging::Post`.
-- **Migration not running** — package migrations are auto-included. If they aren't running, check `config/packages.rb` is loaded from `application.rb`.
-- **Cross-package association fails** — use `blogging/post:belongs_to` in `pu:res:scaffold`, OR manually set `class_name: "Blogging::Post"` on the `belongs_to`.
+- **Class not loading**: namespace must match the directory: `app/models/blogging/post.rb` MUST be `Blogging::Post`.
+- **Migration not running**: package migrations are auto-included. If they aren't running, check `config/packages.rb` is loaded from `application.rb`.
+- **Cross-package association fails**: use `blogging/post:belongs_to` in `pu:res:scaffold`, OR manually set `class_name: "Blogging::Post"` on the `belongs_to`.
 
 ## Related
 
-- [Reference › App › Packages](/reference/app/packages) — full package surface
-- [Reference › App › Portals](/reference/app/portals) — portal-specific configuration
-- [Adding resources](./adding-resources) — `pu:res:scaffold` and `pu:res:conn`
-- [Authentication](./authentication) — portal auth setup
+- [Reference › App › Packages](/reference/app/packages): full package surface
+- [Reference › App › Portals](/reference/app/portals): portal-specific configuration
+- [Adding resources](./adding-resources): `pu:res:scaffold` and `pu:res:conn`
+- [Authentication](./authentication): portal auth setup