plutonium 0.50.0 → 0.51.0

data/docs/.vitepress/config.ts

@@ -21,6 +21,7 @@ export default defineConfig(withMermaid({
     ["meta", { name: "twitter:image", content: "https://radioactive-labs.github.io/plutonium-core/og-image.png" }],
   ],
   ignoreDeadLinks: 'localhostLinks',
+  srcExclude: ['superpowers/**'],
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: "/plutonium.png",
@@ -111,65 +112,74 @@ export default defineConfig(withMermaid({
           ]
         },
         {
-          text: "Model",
+          text: "App",
           collapsed: false,
           items: [
-            { text: "Model", link: "/reference/model/" },
-            { text: "Features", link: "/reference/model/features" },
+            { text: "Overview", link: "/reference/app/" },
+            { text: "Packages", link: "/reference/app/packages" },
+            { text: "Portals", link: "/reference/app/portals" },
+            { text: "Generators", link: "/reference/app/generators" },
           ]
         },
         {
-          text: "Definition",
+          text: "Resource",
           collapsed: false,
           items: [
-            { text: "Definition", link: "/reference/definition/" },
-            { text: "Fields", link: "/reference/definition/fields" },
-            { text: "Actions", link: "/reference/definition/actions" },
-            { text: "Query", link: "/reference/definition/query" },
+            { text: "Overview", link: "/reference/resource/" },
+            { text: "Model", link: "/reference/resource/model" },
+            { text: "Definition", link: "/reference/resource/definition" },
+            { text: "Query", link: "/reference/resource/query" },
+            { text: "Actions", link: "/reference/resource/actions" },
           ]
         },
         {
-          text: "Policy",
+          text: "Behavior",
           collapsed: false,
           items: [
-            { text: "Policy", link: "/reference/policy/" },
+            { text: "Overview", link: "/reference/behavior/" },
+            { text: "Controllers", link: "/reference/behavior/controllers" },
+            { text: "Policies", link: "/reference/behavior/policies" },
+            { text: "Interactions", link: "/reference/behavior/interactions" },
           ]
         },
         {
-          text: "Controller",
+          text: "UI",
           collapsed: false,
           items: [
-            { text: "Controller", link: "/reference/controller/" },
+            { text: "Overview", link: "/reference/ui/" },
+            { text: "Pages", link: "/reference/ui/pages" },
+            { text: "Forms", link: "/reference/ui/forms" },
+            { text: "Displays", link: "/reference/ui/displays" },
+            { text: "Tables", link: "/reference/ui/tables" },
+            { text: "Components", link: "/reference/ui/components" },
+            { text: "Layouts", link: "/reference/ui/layouts" },
+            { text: "Assets", link: "/reference/ui/assets" },
           ]
         },
         {
-          text: "Interaction",
-          collapsed: false,
-          items: [
-            { text: "Interaction", link: "/reference/interaction/" },
-          ]
-        },
-        {
-          text: "Views",
+          text: "Auth",
           collapsed: false,
           items: [
-            { text: "Views", link: "/reference/views/" },
-            { text: "Forms", link: "/reference/views/forms" },
+            { text: "Overview", link: "/reference/auth/" },
+            { text: "Accounts", link: "/reference/auth/accounts" },
+            { text: "Profile", link: "/reference/auth/profile" },
           ]
         },
         {
-          text: "Assets",
+          text: "Tenancy",
           collapsed: false,
           items: [
-            { text: "Assets", link: "/reference/assets/" },
+            { text: "Overview", link: "/reference/tenancy/" },
+            { text: "Entity scoping", link: "/reference/tenancy/entity-scoping" },
+            { text: "Nested resources", link: "/reference/tenancy/nested-resources" },
+            { text: "Invites", link: "/reference/tenancy/invites" },
           ]
         },
         {
-          text: "Infrastructure",
+          text: "Testing",
           collapsed: false,
           items: [
-            { text: "Generators", link: "/reference/generators/" },
-            { text: "Portal", link: "/reference/portal/" },
+            { text: "Overview", link: "/reference/testing/" },
           ]
         }
       ],

data/docs/getting-started/index.md

@@ -1,57 +1,50 @@
 # Getting Started
 
-Welcome to Plutonium! This guide will help you get up and running quickly.
-
-## What You'll Learn
-
-- How to install Plutonium in a new or existing Rails application
-- The basic concepts behind Plutonium's architecture
-- How to create your first resource and connect it to a portal
+Welcome to Plutonium.
 
 ## Prerequisites
 
-Before you begin, make sure you have:
-
-- **Ruby 3.2+** installed
+- **Ruby 3.2+**
 - **Rails 7.2+** (Rails 8 recommended)
 - **Node.js 18+** (for asset compilation)
 - Basic familiarity with Ruby on Rails
 
-## Choose Your Path
+## Pick your starting point
 
-### New Application
+### New Rails app
 
-If you're starting fresh, use our application template:
+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 creates a fully configured Plutonium application with authentication ready to go.
+This sets up Rails + Propshaft + esbuild + TailwindCSS + Plutonium in one shot, with Rodauth ready to go.
 
-[Continue to Installation →](./installation)
+[→ Installation](./installation)
 
-### Existing Application
+### Existing Rails app
 
-Adding Plutonium to an existing Rails app requires a few more steps but is fully supported.
+For pre-existing apps, use `base.rb` (not `plutonium.rb` — that one runs full app bootstrap and clobbers history):
 
-[Continue to Installation →](./installation#existing-application)
+```bash
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
+```
 
-### Tutorial
+[→ Installation › Existing app](./installation#existing-application)
 
-Want to learn by building? Follow our step-by-step tutorial to create a complete blog application.
+### Tutorial
 
-[Start the Tutorial →](./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.
 
-## Next Steps
+[→ Tutorial](./tutorial/)
 
-After installation, you'll typically:
+## After installation
 
-1. **Create a Feature Package** - Organize your business logic
-2. **Generate Resources** - Create your models and scaffolds
-3. **Create a Portal** - Set up the web interface
-4. **Connect Resources** - Make resources accessible through the portal
-5. **Customize** - Override defaults as needed
+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
 
-Each of these steps is covered in detail in the [Tutorial](./tutorial/).
+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/).

data/docs/getting-started/installation.md

@@ -1,22 +1,15 @@
 # Installation
 
-This guide covers installing Plutonium in both new and existing Rails applications.
+For full installation reference (configuration options, base classes, what `pu:core:install` creates), see [Reference › App](/reference/app/). This page covers the quickest path.
 
-## New Application
-
-The fastest way to get started is with our application template:
+## New application
 
 ```bash
 rails new myapp -a propshaft -j esbuild -c tailwind \
   -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
 ```
 
-This template:
-- Adds the Plutonium gem
-- Configures TailwindCSS 4 with Plutonium's theme
-- Sets up Rodauth for authentication
-- Creates initial migrations
-- Configures the asset pipeline
+This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium — plus Rodauth auth, asset pipeline, and initial migrations.
 
 After the template completes:
 
@@ -26,122 +19,86 @@ rails db:migrate
 bin/dev
 ```
 
-Visit `http://localhost:3000` to see your new application.
+Visit `http://localhost:3000`.
 
-## Existing Application
+## Existing application
 
-### Step 1: Add the Gem
+::: danger Use `base.rb`, not `plutonium.rb`
+The `plutonium.rb` template re-runs full app bootstrap (dotenv, annotate, solid_*, asset config) and creates generic "initial commit" commits that clobber history. For any pre-existing app, always use `base.rb`.
+:::
 
-Add Plutonium to your Gemfile:
+### Option 1: Template
 
-```ruby
-gem "plutonium"
+```bash
+bin/rails app:template \
+  LOCATION=https://radioactive-labs.github.io/plutonium-core/templates/base.rb
 ```
 
-Then install:
+### Option 2: Manual
 
-```bash
-bundle install
+```ruby
+# Gemfile
+gem "plutonium"
 ```
 
-### Step 2: Run the Installer
-
 ```bash
+bundle install
 rails generate pu:core:install
 ```
 
-This generator:
-- Creates the Plutonium initializer
-- Adds required configurations
-- Sets up the asset pipeline integration
-
-### Step 3: Install Rodauth (Optional)
-
-If you want Plutonium's built-in authentication:
+## Optional: authentication
 
 ```bash
 rails generate pu:rodauth:install
-```
-
-This creates:
-- Rodauth configuration files
-- Account model and migrations
-- Email templates for authentication flows
-
-### Step 4: Run Migrations
-
-```bash
+rails generate pu:rodauth:account user
 rails db:migrate
 ```
 
-### Step 5: Configure Assets
+For account options and customization, see [Reference › Auth](/reference/auth/) and [Guides › Authentication](/guides/authentication).
 
-Run the assets generator to set up TailwindCSS and Plutonium styles:
+## Optional: assets toolchain
 
 ```bash
 rails generate pu:core:assets
 ```
 
-This configures PostCSS, TailwindCSS, and imports Plutonium's styles into your application.
-
-## Verifying Installation
+Installs npm packages, creates `tailwind.config.js` extending Plutonium's config, imports Plutonium CSS, registers Stimulus controllers. Required if you want to customize the theme — see [Reference › UI › Assets](/reference/ui/assets) and [Guides › Theming](/guides/theming).
 
-After installation, verify everything is working:
+## Verify
 
 ```bash
 rails runner "puts Plutonium::VERSION"
 ```
 
-You should see the installed version number.
-
 ## Configuration
 
-Plutonium is configured in `config/initializers/plutonium.rb`:
-
 ```ruby
+# config/initializers/plutonium.rb
 Plutonium.configure do |config|
-  # Load default settings for version 1.0
   config.load_defaults 1.0
 
-  # Development mode (auto-detected from PLUTONIUM_DEV env var)
-  # config.development = true
-
-  # Cache discovery (defaults to true in production, false in development)
-  # config.cache_discovery = false
+  # config.shell = :classic            # legacy chrome (only for upgrades)
 
-  # Hot reloading (defaults to true in development)
-  # config.enable_hotreload = true
-
-  # Asset configuration
-  # config.assets.logo = "custom_logo.png"
-  # config.assets.favicon = "custom_favicon.ico"
-  # config.assets.stylesheet = "plutonium.css"
-  # config.assets.script = "plutonium.min.js"
+  # Custom assets (after running pu:core:assets)
+  # config.assets.stylesheet = "application"
+  # config.assets.script     = "application"
+  # config.assets.logo       = "custom_logo.png"
+  # config.assets.favicon    = "custom_favicon.ico"
 end
 ```
 
-## Development Setup
-
-For the best development experience:
+Full configuration options: [Reference › App](/reference/app/#configuration).
 
-### 1. Use bin/dev
+## `bin/dev` for development
 
-Plutonium includes a Procfile for `foreman`:
+Plutonium ships a Procfile that runs Rails and the CSS watcher together:
 
 ```bash
 bin/dev
 ```
 
-This starts Rails and the CSS watcher together.
-
-### 2. Enable Reloading
-
-In development, Plutonium automatically reloads definitions and policies when files change. This is controlled by `config.enable_hotreload` (enabled by default in development).
-
-## Next Steps
-
-Now that Plutonium is installed:
+## Next steps
 
-- [Create your first Feature Package](/guides/creating-packages)
-- [Generate a Resource](/guides/adding-resources)
-- [Follow the Tutorial](/getting-started/tutorial/)
+- [Tutorial](./tutorial/) — build a complete blog application step-by-step
+- [Adding resources](/guides/adding-resources) — create your first resource
+- [Creating packages](/guides/creating-packages) — organize code into feature and portal packages

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)