plutonium 0.50.0 → 0.52.0

data/docs/.vitepress/theme/components/SectionLanding.vue

@@ -0,0 +1,115 @@
+<template>
+  <section class="pu-section sl-section">
+    <div class="pu-section-inner">
+      <div class="pu-eyebrow">{{ eyebrow }}</div>
+      <h1 class="sl-h1">{{ title }}</h1>
+      <p class="sl-lede">{{ lede }}</p>
+
+      <div class="sl-grid">
+        <div class="sl-rail">
+          <template v-if="mode === 'numbered'">
+            <a
+              v-for="(step, i) in rail"
+              :key="i"
+              :href="step.link"
+              :class="['sl-step', { 'sl-step--link': step.link }]"
+            >
+              <span class="sl-num">{{ i + 1 }}</span>
+              <span class="sl-step-body">
+                <span class="sl-step-name">{{ step.name }}</span>
+                <span v-if="step.desc" class="sl-step-desc">{{ step.desc }}</span>
+              </span>
+            </a>
+          </template>
+          <template v-else>
+            <div v-for="grp in rail" :key="grp.group" class="sl-group">
+              <div class="sl-group-name">{{ grp.group }}</div>
+              <a
+                v-for="item in grp.items"
+                :key="item.name"
+                :href="item.link"
+                class="sl-step sl-step--link sl-step--cat"
+              >
+                <span class="sl-step-body">
+                  <span class="sl-step-name">{{ item.name }}</span>
+                  <span v-if="item.desc" class="sl-step-desc">{{ item.desc }}</span>
+                </span>
+                <IconArrowRight class="sl-step-arrow" :size="16" :stroke-width="2" />
+              </a>
+            </div>
+          </template>
+        </div>
+
+        <aside class="sl-aside">
+          <div v-for="block in sidebar" :key="block.heading" class="sl-aside-block">
+            <h4 class="sl-aside-heading">{{ block.heading }}</h4>
+            <ul>
+              <li v-for="item in block.items" :key="item.label">
+                <a :href="item.href">{{ item.label }}</a>
+                <span v-if="item.note" class="sl-aside-note"> — {{ item.note }}</span>
+              </li>
+            </ul>
+          </div>
+        </aside>
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { IconArrowRight } from "@tabler/icons-vue"
+
+defineProps({
+  eyebrow: { type: String, required: true },
+  title: { type: String, required: true },
+  lede: { type: String, required: true },
+  rail: { type: Array, required: true },
+  mode: { type: String, default: "numbered", validator: v => ["numbered", "categorized"].includes(v) },
+  sidebar: { type: Array, default: () => [] },
+})
+</script>
+
+<style scoped>
+.sl-section { padding: 64px 24px 96px; }
+.sl-h1 { font-size: 36px; letter-spacing: -0.025em; margin: 0 0 12px; color: var(--pu-text); }
+.sl-lede { font-size: 16px; color: var(--pu-text-muted); max-width: 640px; margin: 0 0 40px; line-height: 1.55; }
+.sl-grid { display: grid; grid-template-columns: 1.4fr 1fr; gap: 48px; }
+.sl-rail { border-left: 2px solid var(--pu-accent); padding-left: 24px; }
+.sl-group + .sl-group { margin-top: 22px; }
+.sl-group-name {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.1em;
+  color: var(--pu-accent); font-weight: 600; margin-bottom: 8px;
+}
+.sl-step {
+  display: flex; gap: 12px; align-items: flex-start;
+  padding: 12px 0; border-bottom: 1px solid var(--pu-border-soft);
+  color: var(--pu-text); text-decoration: none;
+}
+.sl-step:last-child { border-bottom: none; }
+.sl-step--cat { justify-content: space-between; align-items: center; }
+.sl-step--link:hover .sl-step-name { color: var(--pu-accent); }
+.sl-step--link:hover .sl-step-arrow { transform: translateX(2px); color: var(--pu-accent); }
+.sl-num {
+  flex-shrink: 0; width: 24px; height: 24px; line-height: 24px; text-align: center;
+  background: var(--pu-accent); color: #fff; border-radius: 50%;
+  font-size: 11px; font-weight: 600;
+}
+.sl-step-body { display: flex; flex-direction: column; gap: 2px; flex: 1; }
+.sl-step-name { font-weight: 600; font-size: 14px; }
+.sl-step-desc { font-size: 12.5px; color: var(--pu-text-muted); }
+.sl-step-arrow { color: var(--pu-text-faint); transition: transform 0.15s ease, color 0.15s ease; flex-shrink: 0; }
+
+.sl-aside-block + .sl-aside-block { margin-top: 28px; }
+.sl-aside-heading {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.1em;
+  color: var(--pu-text-faint); margin: 0 0 10px; font-weight: 600;
+}
+.sl-aside ul { list-style: none; padding: 0; margin: 0; font-size: 14px; line-height: 1.85; }
+.sl-aside a { color: var(--pu-accent); text-decoration: none; font-weight: 500; }
+.sl-aside a:hover { text-decoration: underline; }
+.sl-aside-note { color: var(--pu-text-muted); font-weight: 400; }
+
+@media (max-width: 900px) {
+  .sl-grid { grid-template-columns: 1fr; gap: 32px; }
+}
+</style>

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,57 +1,33 @@
-# 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
-
-## Prerequisites
-
-Before you begin, make sure you have:
-
-- **Ruby 3.2+** installed
-- **Rails 7.2+** (Rails 8 recommended)
-- **Node.js 18+** (for asset compilation)
-- Basic familiarity with Ruby on Rails
-
-## Choose Your Path
-
-### New Application
-
-If you're starting fresh, use our 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.
-
-[Continue to Installation →](./installation)
-
-### Existing Application
-
-Adding Plutonium to an existing Rails app requires a few more steps but is fully supported.
-
-[Continue to Installation →](./installation#existing-application)
-
-### Tutorial
-
-Want to learn by building? Follow our step-by-step tutorial to create a complete blog application.
-
-[Start the Tutorial →](./tutorial/)
-
-## Next Steps
-
-After installation, you'll typically:
-
-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
-
-Each of these steps is covered in detail in the [Tutorial](./tutorial/).
+---
+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/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/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