plutonium 0.50.0 → 0.52.0

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/getting-started/tutorial/index.md

@@ -55,13 +55,12 @@ Create a second portal with different access levels for content authors.
 ### [8. Customizing the UI](./08-customizing-ui)
 Customize forms, tables, and views to match your requirements.
 
-## Getting Help
+## Getting help
 
 If you get stuck:
-- Check the [Guides](/guides/) for detailed explanations
-- Browse the [Reference Documentation](/reference/) for API details
-- Visit our [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues)
 
-Let's get started!
+- 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/).
+- Visit [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues).
 
 [Begin Chapter 1: Project Setup →](./01-setup)