plutonium 0.51.0 → 0.52.0

data/docs/.vitepress/theme/custom.css

@@ -418,3 +418,147 @@ Brand Colors:
   line-height: 1.5;
   padding-bottom: 4px;
 }
+
+/* ===== Public-pages design tokens (2026-05) ===== */
+:root {
+  --pu-bg-dark: #0d1117;
+  --pu-bg-dark-2: #161b22;
+  --pu-bg-light: #ffffff;
+  --pu-bg-band: #fafafa;
+  --pu-border: #e0e0e0;
+  --pu-border-soft: #ececec;
+  --pu-text: #1a1a1a;
+  --pu-text-muted: #666666;
+  --pu-text-faint: #888888;
+  --pu-accent: #d33;
+  --pu-accent-soft: #fff7f7;
+  --pu-success-bg: #ecf9f1;
+  --pu-success-fg: #0a7c3f;
+  --pu-warn-bg: #fdf3e6;
+  --pu-warn-fg: #a86b00;
+  --pu-term-prompt: #7ee787;
+  --pu-term-cursor: #58a6ff;
+  --pu-term-text: #e6edf3;
+}
+
+.dark {
+  --pu-bg-light: #0d1117;
+  --pu-bg-band: #161b22;
+  --pu-text: #e6edf3;
+  --pu-text-muted: #9da7b1;
+  --pu-text-faint: #6e7681;
+  --pu-border: #30363d;
+  --pu-border-soft: #21262d;
+}
+
+/* Eyebrow */
+.pu-eyebrow {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--pu-accent);
+  font-weight: 600;
+  margin-bottom: 8px;
+}
+.pu-eyebrow--muted { color: var(--pu-text-faint); }
+
+/* Buttons */
+.pu-btn {
+  display: inline-block;
+  padding: 10px 18px;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  text-decoration: none;
+  transition: opacity 0.15s ease;
+}
+.pu-btn:hover { opacity: 0.85; }
+.pu-btn:focus-visible {
+  outline: 2px solid var(--pu-accent);
+  outline-offset: 2px;
+}
+.pu-btn-primary { background: var(--pu-accent); color: #ffffff; }
+.pu-btn-ghost {
+  border: 1px solid currentColor;
+  color: var(--pu-text);
+  opacity: 0.85;
+}
+.pu-btn-ghost.on-dark { color: #e6edf3; border-color: rgba(255,255,255,0.25); }
+
+/* Terminal block */
+.pu-term {
+  background: var(--pu-bg-dark);
+  color: var(--pu-term-text);
+  border-radius: 8px;
+  padding: 16px 18px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+  line-height: 1.7;
+  overflow-x: auto;
+}
+.pu-term--inline { padding: 12px 14px; font-size: 12.5px; }
+.pu-term .prompt { color: var(--pu-term-prompt); }
+.pu-term .dim { opacity: 0.55; }
+.pu-term-cursor {
+  background: var(--pu-term-cursor);
+  display: inline-block;
+  width: 7px;
+  height: 13px;
+  vertical-align: text-bottom;
+  animation: pu-blink 1s steps(2) infinite;
+}
+@keyframes pu-blink { 50% { opacity: 0; } }
+@media (prefers-reduced-motion: reduce) {
+  .pu-term-cursor { animation: none; }
+}
+
+/* Section frames */
+.pu-section {
+  padding: 64px 24px;
+}
+.pu-section--dark {
+  background: var(--pu-bg-dark);
+  color: var(--pu-term-text);
+}
+.pu-section--band {
+  background: var(--pu-bg-band);
+}
+.pu-section .pu-section-inner {
+  max-width: 1100px;
+  margin: 0 auto;
+}
+.pu-section-title {
+  font-size: 28px;
+  letter-spacing: -0.02em;
+  margin: 0 0 24px;
+  color: var(--pu-text);
+}
+.pu-section--dark .pu-section-title { color: var(--pu-term-text); }
+
+.vp-doc img:not(a img),
+img.pu-zoomable { cursor: zoom-in; }
+.medium-zoom-overlay { z-index: 100; }
+.medium-zoom-image--opened { z-index: 101; }
+
+.pu-zoom-close {
+  position: fixed;
+  top: 16px;
+  right: 16px;
+  z-index: 102;
+  width: 40px;
+  height: 40px;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-1);
+  border-radius: 50%;
+  font-size: 24px;
+  line-height: 1;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  transition: background 0.15s ease, transform 0.15s ease;
+}
+.pu-zoom-close:hover { background: var(--vp-c-bg-mute); transform: scale(1.05); }
+.pu-zoom-close:focus-visible { outline: 2px solid var(--vp-c-brand-1); outline-offset: 2px; }

data/docs/.vitepress/theme/index.ts

@@ -1,4 +1,61 @@
 import DefaultTheme from "vitepress/theme"
+import { onMounted, watch, nextTick } from "vue"
+import { useRoute } from "vitepress"
+import mediumZoom from "medium-zoom"
 import "./custom.css"
 
-export default DefaultTheme
+import HomeHero from "./components/HomeHero.vue"
+import HomeStopWriting from "./components/HomeStopWriting.vue"
+import HomePillars from "./components/HomePillars.vue"
+import HomeWalkthrough from "./components/HomeWalkthrough.vue"
+import HomeAudienceSplit from "./components/HomeAudienceSplit.vue"
+import HomeInTheBox from "./components/HomeInTheBox.vue"
+import HomeCta from "./components/HomeCta.vue"
+import SectionLanding from "./components/SectionLanding.vue"
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component("HomeHero", HomeHero)
+    app.component("HomeStopWriting", HomeStopWriting)
+    app.component("HomePillars", HomePillars)
+    app.component("HomeWalkthrough", HomeWalkthrough)
+    app.component("HomeAudienceSplit", HomeAudienceSplit)
+    app.component("HomeInTheBox", HomeInTheBox)
+    app.component("HomeCta", HomeCta)
+    app.component("SectionLanding", SectionLanding)
+  },
+  setup() {
+    const route = useRoute()
+
+    let closeBtn: HTMLButtonElement | null = null
+
+    const attachCloseButton = (z: ReturnType<typeof mediumZoom>) => {
+      z.on("opened", () => {
+        const overlay = document.querySelector<HTMLElement>(".medium-zoom-overlay")
+        if (!overlay) return
+        closeBtn = document.createElement("button")
+        closeBtn.type = "button"
+        closeBtn.setAttribute("aria-label", "Close")
+        closeBtn.className = "pu-zoom-close"
+        closeBtn.innerHTML = "&times;"
+        closeBtn.addEventListener("click", () => z.close())
+        document.body.appendChild(closeBtn)
+      })
+      z.on("close", () => {
+        closeBtn?.remove()
+        closeBtn = null
+      })
+    }
+
+    const zoom = () => {
+      const z = mediumZoom(".vp-doc img:not(a img), img.pu-zoomable", {
+        background: "var(--vp-c-bg)",
+        margin: 16,
+      })
+      attachCloseButton(z)
+    }
+    onMounted(() => nextTick(zoom))
+    watch(() => route.path, () => nextTick(zoom))
+  }
+}

data/docs/getting-started/index.md

@@ -1,50 +1,33 @@
-# Getting Started
-
-Welcome to Plutonium.
-
-## Prerequisites
-
-- **Ruby 3.2+**
-- **Rails 7.2+** (Rails 8 recommended)
-- **Node.js 18+** (for asset compilation)
-- Basic familiarity with Ruby on Rails
-
-## Pick your starting point
-
-### New Rails app
-
-The fastest way — use the application template:
-
-```bash
-rails new myapp -a propshaft -j esbuild -c tailwind \
-  -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
-```
-
-This sets up Rails + Propshaft + esbuild + TailwindCSS + Plutonium in one shot, with Rodauth ready to go.
-
-[→ Installation](./installation)
-
-### Existing Rails app
-
-For pre-existing apps, use `base.rb` (not `plutonium.rb` — that one runs full app bootstrap and clobbers history):
-
-```bash
-bin/rails app:template \
-  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
-```
-
-[→ Installation › Existing app](./installation#existing-application)
-
-### Tutorial
-
-Want to learn by building? The [8-step tutorial](./tutorial/) walks through a complete blog app — auth, authorization, custom actions, nested resources, multi-portal.
-
-[→ Tutorial](./tutorial/)
-
-## After installation
-
-1. **Create resources** with `pu:res:scaffold` (see [Adding resources](/guides/adding-resources))
-2. **Connect them to a portal** with `pu:res:conn`
-3. **Customize** the definition, policy, controller as needed
-
-Reference for each layer: [App](/reference/app/), [Resource](/reference/resource/), [Behavior](/reference/behavior/), [UI](/reference/ui/), [Auth](/reference/auth/), [Tenancy](/reference/tenancy/), [Testing](/reference/testing/).
+---
+layout: page
+sidebar: false
+aside: false
+---
+
+<SectionLanding
+  eyebrow="Getting Started"
+  title="Learn Plutonium by building."
+  lede="Walk the path top to bottom, or skip to the part you need."
+  mode="numbered"
+  :rail="[
+    { name: 'Project setup', desc: 'Bootstrap a Rails app with the Plutonium template.', link: '/plutonium-core/getting-started/tutorial/01-setup' },
+    { name: 'First resource', desc: 'Model, definition, scaffold, connect to a portal.', link: '/plutonium-core/getting-started/tutorial/02-first-resource' },
+    { name: 'Authentication', desc: 'Add Rodauth with login + signup.', link: '/plutonium-core/getting-started/tutorial/03-authentication' },
+    { name: 'Authorization', desc: 'ActionPolicy-scoped resource access.', link: '/plutonium-core/getting-started/tutorial/04-authorization' },
+    { name: 'Custom actions', desc: 'Add a domain-specific action to a resource.', link: '/plutonium-core/getting-started/tutorial/05-custom-actions' },
+    { name: 'Nested resources', desc: 'Posts → Comments, scoped through routing.', link: '/plutonium-core/getting-started/tutorial/06-nested-resources' },
+    { name: 'Author portal', desc: 'A second portal with its own auth and pages.', link: '/plutonium-core/getting-started/tutorial/07-author-portal' },
+    { name: 'Customizing UI', desc: 'Theme tokens, custom Phlex components, layouts.', link: '/plutonium-core/getting-started/tutorial/08-customizing-ui' },
+  ]"
+  :sidebar="[
+    { heading: 'Already know your way around?', items: [
+      { label: 'Installation', href: '/plutonium-core/getting-started/installation', note: 'bootstrap a new app' },
+      { label: 'Concepts overview', href: '/plutonium-core/reference/' },
+      { label: 'Generators reference', href: '/plutonium-core/reference/app/generators' },
+    ]},
+    { heading: 'Need help?', items: [
+      { label: 'GitHub Discussions', href: 'https://github.com/radioactive-labs/plutonium-core/discussions' },
+      { label: 'Open an issue', href: 'https://github.com/radioactive-labs/plutonium-core/issues' },
+    ]},
+  ]"
+/>

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

@@ -118,13 +118,13 @@ rails db:migrate
 
 ## Creating a Portal
 
-Resources need a portal to be accessible via the web. Let's create an admin portal:
+Resources need a portal to be accessible via the web. Let's create a public admin portal so we can explore the UI right away — we'll add authentication in [Chapter 3](./03-authentication).
 
 ```bash
-rails generate pu:pkg:portal admin
+rails generate pu:pkg:portal admin --public
 ```
 
-This creates the AdminPortal package with authentication configured.
+This creates the `AdminPortal` package mounted at `/admin`. The `--public` flag wires the portal's controller with `Plutonium::Auth::Public`, so any visitor can access it. (Other options: `--auth=ACCOUNT` to gate via a Rodauth account, or `--byo` for your own auth.)
 
 ## Connecting the Resource
 
@@ -145,12 +145,21 @@ This:
 bin/dev
 ```
 
-Visit `http://localhost:3000/admin/blogging/posts`. You should see:
-- An empty posts table
-- A "New Post" button
-- Search and filter options
+Visit `http://localhost:3000/admin/blogging/posts`. You should see an empty posts table with a "New Post" button:
 
-Try creating a post. The form is automatically generated from your model's attributes.
+![Empty posts index](/images/tutorial/02-empty-index.png)
+
+Click "New" — the form is automatically generated from your model's attributes. By default Plutonium opens it as a slideover (right) so you keep the index visible; visiting `/admin/blogging/posts/new` directly renders the same form as a standalone page (left):
+
+| Default — slideover from index | Standalone page (direct URL) |
+|:--:|:--:|
+| ![Slideover new form](/images/tutorial/02-new-form-modal.png) | ![Standalone new form](/images/tutorial/02-new-form.png) |
+
+To always render full-page instead, set `modal false` in the definition. To pick a different style, use `modal :centered`. See [Reference › Resource › Definition › Modal](/reference/resource/definition).
+
+Create a few posts and the table fills in:
+
+![Posts index with rows](/images/tutorial/02-index-with-posts.png)
 
 ## Understanding Auto-Detection
 

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

@@ -12,23 +12,27 @@ Rodauth is a Ruby authentication framework that Plutonium uses for:
 
 Plutonium integrates Rodauth seamlessly with its portal system.
 
-## Setting Up Authentication
+## Installing Rodauth
 
-If you used the Plutonium template, Rodauth is already installed. If not:
+Run the Plutonium Rodauth installer once per app — it creates the Rodauth app, plugin, and initializer:
 
 ```bash
 rails generate pu:rodauth:install
-rails db:migrate
 ```
 
+(No migration is needed yet; the account-type generator below creates its own tables.)
+
 ## Creating an Account Type
 
-Plutonium supports multiple account types. For admin accounts that cannot self-register, use the `admin` generator:
+Plutonium supports multiple account types. For admins, use the dedicated `pu:rodauth:admin` generator — it's a preset on top of `pu:rodauth:account` that enables 2FA, lockout, audit logging, and disables public signup:
 
 ```bash
 rails generate pu:rodauth:admin admin
+rails db:migrate
 ```
 
+For self-service user accounts, the corresponding command is `rails generate pu:rodauth:account user`.
+
 This creates:
 
 ### Account Model (`app/models/admin.rb`)
@@ -57,30 +61,28 @@ end
 
 The generator also creates migrations for the account table and authentication features.
 
-## Configuring the Portal
+## Gating the Portal with Authentication
 
-Authentication is configured in the portal's controller concern. Update it to use Rodauth:
+In [Chapter 2](./02-first-resource) you generated the admin portal with `--public`. Now that you have an `admin` Rodauth account, swap the portal over to require login. The fastest way is to re-run the portal generator with `--auth=admin --force`:
 
-```ruby
-# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
-module AdminPortal
-  module Concerns
-    module Controller
-      extend ActiveSupport::Concern
-      include Plutonium::Portal::Controller
-      include Plutonium::Auth::Rodauth(:admin)
-    end
-  end
-end
+```bash
+rails generate pu:pkg:portal admin --auth=admin --force
 ```
 
-This provides `current_user` and authentication helpers throughout the portal.
+This updates two files:
 
-## Running Migrations
+- `packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb` — swaps `include Plutonium::Auth::Public` for `include Plutonium::Auth::Rodauth(:admin)`, giving you `current_user`, `logout_url`, and `profile_url` helpers throughout the portal.
+- `packages/admin_portal/config/routes.rb` — wraps the engine mount in a routes-level constraint:
 
-```bash
-rails db:migrate
-```
+  ```ruby
+  constraints Rodauth::Rails.authenticate(:admin) do
+    mount AdminPortal::Engine, at: "/admin"
+  end
+  ```
+
+The routes constraint is what actually gates access — unauthenticated requests to `/admin/*` are redirected to `/admins/login` before they hit any controller or policy.
+
+(If you prefer not to regenerate, you can apply both edits by hand — they're shown above.)
 
 ## Testing Authentication
 
@@ -90,7 +92,13 @@ Restart your server:
 bin/dev
 ```
 
-Visit `http://localhost:3000/admin/blogging/posts`. You'll be redirected to the login page.
+Visit `http://localhost:3000/admin/blogging/posts`. You'll be redirected to the login page:
+
+![Admin login page](/images/tutorial/03-login.png)
+
+The "Create a New Account" link goes to the same Rodauth-rendered account creation form:
+
+![Create account page](/images/tutorial/03-create-account.png)
 
 ### Creating an Admin Account
 

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

@@ -79,10 +79,15 @@ end
 
 ## Testing the Action
 
-1. Create an unpublished post
-2. View the post details
-3. Click the "Publish" action button
-4. The post is now published
+Open any unpublished post and click **Actions** in the top-right — the "Publish Post" item appears with its Tabler icon:
+
+![Publish action in the show page menu](/images/tutorial/05-actions-menu.png)
+
+It also shows on each table row's `⋮` menu — same action, available wherever the record is rendered:
+
+![Publish action in the row menu](/images/tutorial/05-row-actions.png)
+
+Click "Publish Post" and the post is updated; the flash banner confirms success.
 
 ## Actions with User Input
 

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

@@ -69,7 +69,13 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
 end
 ```
 
-The panel links to the nested comments route and shows "Add Comment" if the user has permission.
+The post show page now has tabs — **Details** and **Comments** — driven by the associations you permit:
+
+![Post show page with Details and Comments tabs](/images/tutorial/06-post-with-comments.png)
+
+Clicking **Comments** opens the nested index for that post — a complete sub-resource view with its own paginated table, "New" button, and row actions:
+
+![Nested comments index](/images/tutorial/06-comments-tab.png)
 
 ## Comment Policy
 

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

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

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

@@ -117,6 +117,10 @@ class Blogging::PostDefinition < Blogging::ResourceDefinition
 end
 ```
 
+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:
 
 ```ruby

data/docs/guides/authentication.md

@@ -22,10 +22,10 @@ rails db:migrate
 #    (when you run `pu:pkg:portal admin --auth=user`, this happens automatically)
 ```
 
-Then mount your portal with the auth constraint:
+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
-# config/routes.rb
+# packages/admin_portal/config/routes.rb (generated)
 Rails.application.routes.draw do
   constraints Rodauth::Rails.authenticate(:user) do
     mount AdminPortal::Engine, at: "/admin"
@@ -33,6 +33,8 @@ Rails.application.routes.draw do
 end
 ```
 
+If you generated the portal as `--public` and need to switch it to authenticated later, re-run with `--auth=user --force` (or edit the constraint into the routes file by hand).
+
 For accounts with more features, options, and admin patterns: see [Reference › Auth › Accounts](/reference/auth/accounts).
 
 ## Common variations
@@ -47,18 +49,21 @@ Then enable in the user-facing security section (see [User profile](./user-profi
 
 ### Hardened admin account
 
-For an admin role with 2FA required, lockout, audit logging, and no public signup:
+For an admin role with 2FA, lockout, audit logging, and no public signup, use the dedicated `pu:rodauth:admin` generator (a preset of `pu:rodauth:account` with hardened defaults):
 
 ```bash
 rails generate pu:rodauth:admin admin
 ```
 
-Create the first admin with the rake task:
+Create the first admin with the rake task generated alongside the account:
 
 ```bash
-rails rodauth_admin:create[admin@example.com,password123]
+EMAIL=admin@example.com rails rodauth:admin
+# (run without EMAIL to prompt)
 ```
 
+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
 
 ```bash

data/docs/guides/authorization.md

@@ -18,7 +18,7 @@ Every policy controls three things:
 
 - **`create?` and `read?` default to `false`.** Always override them explicitly. Derived methods (`update?`, `show?`, `index?`) inherit automatically.
 - **`permitted_attributes_for_*` must be explicit in production.** Dev auto-detects; production raises.
-- **`relation_scope` must call `default_relation_scope(relation)` explicitly** — never `super`. See [Reference › Behavior › Policies](/reference/behavior/policies).
+- **`relation_scope` must end up calling `default_relation_scope(relation)` somewhere in the chain.** Prefer calling it explicitly in your override. `super` is fine when extending a parent policy (e.g., a package-level base) that itself calls `default_relation_scope`. See [Reference › Behavior › Policies](/reference/behavior/policies).
 - **Custom action ⇒ policy method.** `action :publish` needs `def publish?` on the policy. Undefined methods return `false` → action silently disappears.
 
 ## Steps
@@ -93,7 +93,7 @@ relation_scope do |relation|
 end
 ```
 
-🚨 Always call `default_relation_scope(relation)` explicitly — not `super`. Bypassing it triggers `verify_default_relation_scope_applied!` at runtime.
+🚨 `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
 
@@ -244,7 +244,7 @@ end
 - **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` doesn't behave as expected** — use `default_relation_scope(relation)` explicitly; `super`'s semantics depend on how ActionPolicy registered the scope.
+- **`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
 

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 have NO routes, views, or controllers. Portal packages have NO models or interactions.
+🚨 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
 
@@ -64,21 +64,18 @@ Options:
 - `--byo` — bring your own auth.
 - `--scope=CLASS` — entity class for multi-tenancy.
 
-### 2. Mount it
+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.
 
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  constraints Rodauth::Rails.authenticate(:user) do
-    mount AdminPortal::Engine, at: "/admin"
-  end
-end
+### 2. Connect resources
+
+```bash
+rails g pu:res:conn Blogging::Post --dest=admin_portal
 ```
 
-### 3. Connect resources
+You can connect multiple resources in one command:
 
 ```bash
-rails g pu:res:conn Post Blogging::Post --dest=admin_portal
+rails g pu:res:conn Blogging::Post Blogging::Comment --dest=admin_portal
 ```
 
 See [Reference › App › Portals](/reference/app/portals) for the full portal surface.

data/docs/guides/custom-actions.md

@@ -139,7 +139,12 @@ def bulk_archive?
 end
 ```
 
-The UI only shows bulk actions ALL selected records support.
+Two related behaviors:
+
+- A row gets a `✕` instead of a checkbox when **no** bulk action applies to it (no `*_bulk?` policy method on that record returns true).
+- A bulk action only appears in the toolbar when **every selected row** supports it. Mixing one unsupported row hides the action until you deselect.
+
+![Bulk action toolbar with selected drafts](/images/guides/custom-actions-bulk.png)
 
 ## Resource action (no specific record)