plutonium 0.65.0 → 0.66.0

data/docs/.vitepress/sync-skills.mjs

@@ -20,7 +20,10 @@ for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
   if (!existsSync(source)) continue // skip dirs that aren't skills (no SKILL.md)
   let content = readFileSync(source, "utf8")
 
-  const description = content.match(/^description:\s*(.+)$/m)?.[1] ?? ""
+  // Descriptions are single-quoted YAML scalars (they contain ": "), so strip
+  // the quotes and unescape doubled single quotes.
+  const rawDescription = content.match(/^description:\s*(.+)$/m)?.[1] ?? ""
+  const description = rawDescription.match(/^'(.*)'$/)?.[1].replaceAll("''", "'") ?? rawDescription
 
   // Wiki-style [[skill-name]] cross-links become relative markdown links so
   // crawlers can follow them between the published files.
@@ -34,11 +37,11 @@ skills.sort((a, b) => (a.name === "plutonium" ? -1 : b.name === "plutonium" ? 1
 
 const index = `# Plutonium Skills
 
-Task-focused guides for AI agents working with the [Plutonium](https://radioactive-labs.github.io/plutonium-core/) Rails RAD framework. Each file is self-contained markdown. Start with \`plutonium.md\` — it routes to the others.
+Task-focused guides for AI agents working with the [Plutonium](https://radioactive-labs.github.io/plutonium-core/) Rails RAD framework. Each file is self-contained markdown. Start with \`plutonium.md\`; it routes to the others.
 
 These are the same skills the gem installs into projects via \`rails g pu:skills:sync\` (Claude Code loads them automatically from \`.claude/skills/\`). Any agent can fetch them directly from the URLs below.
 
-${skills.map((s) => `- [${s.name}](${s.name}.md) — ${s.description}`).join("\n")}
+${skills.map((s) => `- [${s.name}](${s.name}.md): ${s.description}`).join("\n")}
 `
 
 writeFileSync(join(outDir, "index.md"), index)

data/docs/blog/introducing-plutonium-dashboards.md

@@ -1,18 +1,17 @@
 ---
 title: "Introducing Plutonium dashboards: metric cards and charts for your Rails admin"
 titleTemplate: "Plutonium Blog"
-date: 2026-10-01
+date: 2026-10-02
 description: Plutonium now ships dashboards. Declare metric, chart and free-form cards in one Ruby class, mount it with one routes line, and every card loads in its own turbo frame inside your portal's auth and tenancy.
 author: Stefan Froelich
 tags: [announcement, dashboards, charts]
-draft: true
 ---
 
 # Introducing Plutonium dashboards: metric cards and charts for your Rails admin
 
 <BlogMeta />
 
-Every portal Plutonium generates opens on a Dashboard page that lists your resources with a record count each. Anything past that, the numbers and charts an admin actually opens the app to see, was yours to build: a controller action, some instance variables, a view. The next release ships it. A dashboard is a Ruby class of cards, mounted with one line in your routes.
+Every portal Plutonium generates opens on a Dashboard page that lists your resources with a record count each. Anything past that, the numbers and charts an admin actually opens the app to see, was yours to build: a controller action, some instance variables, a view. Plutonium 0.65 ships it. A dashboard is a Ruby class of cards, mounted with one line in your routes.
 
 ![A dashboard with four metric cards, an area chart of signups per day, a donut chart and a full-width welcome card](/images/blog/dashboards-overview.png)
 
@@ -20,7 +19,7 @@ Every portal Plutonium generates opens on a Dashboard page that lists your resou
 
 - A class-level DSL with three kinds of card: `metric` for headline numbers, `chart` for charts, `card` for anything else.
 - `register_dashboard`, which draws the routes and a controller that inherits your portal's authentication, tenant scoping and layout.
-- Lazy loading: every card is fetched in its own turbo frame, behind a skeleton.
+- Lazy loading: by default every card is fetched in its own turbo frame, behind a skeleton.
 - A 12-column grid with a default width per kind of card, plus per-card refresh intervals, conditions, links and icons.
 - A `pu:dashboard` generator, and a Dashboards group in the portal sidebar.
 
@@ -102,7 +101,7 @@ The browser fetches each frame as it scrolls into view, and the card's block run
 
 ![The same dashboard before its frames have loaded: every card is a grey skeleton except the Conversion metric, which is already showing 12.5%](/images/blog/dashboards-loading.png)
 
-The Conversion card in that screenshot is declared `lazy: false`, which makes it inline: its block runs in the page request and the finished card is part of the page response, with no frame, no skeleton and no second request. The price is that the page waits for it. Use it for a number cheap enough that a round trip costs more than the query, and leave everything else lazy. An inline card never refreshes, since there is no frame to reload.
+The Conversion card in that screenshot is declared `lazy: false`, which makes it inline: its block runs in the page request and the finished card is part of the page response, with no frame, no skeleton and no second request. The price is that the page waits for it. Use it for a number cheap enough that a round trip costs more than the query, and leave everything else lazy. An inline card never refreshes, since there is no frame to reload, and in development and test an exception in its block fails the whole page rather than one frame.
 
 `refresh 60` on the dashboard reloads every lazy card once a minute. `refresh: 10` on a card overrides it, and `refresh: false` keeps an expensive card out of it. Reloads pause while the tab is hidden and catch up when it becomes visible again, so a dashboard left open overnight is not running your aggregates all night.
 

data/docs/blog/introducing-plutonium-i18n.md

@@ -1,11 +1,10 @@
 ---
 title: "Introducing Plutonium i18n: every string translatable, the Rails way"
 titleTemplate: "Plutonium Blog"
-date: 2026-09-17
+date: 2026-10-02
 description: The text a framework renders has always been the framework's, not yours. Plutonium now routes every string it draws through a locale file, so translating the UI is a matter of YAML and nothing else.
 author: Stefan Froelich
 tags: [announcement, i18n, rails]
-draft: true
 ---
 
 # Introducing Plutonium i18n: every string translatable, the Rails way
@@ -14,7 +13,7 @@ draft: true
 
 You have always been able to translate your own app. Rails has shipped `I18n.t`, per-model attribute names and localized dates since long before you needed them. What you could not translate was the framework on top. The button that says "Create", the "Search..." in the filter box, the flash that a record was saved, the empty-state line, the sentence under the paginator: an admin framework ships those in English, baked into views you adopted the framework precisely so you would never open. Translating them meant forking them.
 
-Plutonium now routes every string it renders through a locale file, and resolves every label it derives from a key through the Rails i18n conventions you already know. Translating the UI is a matter of YAML. Nothing in a definition, a policy or a controller changes.
+Plutonium now routes every string it renders through a locale file, and resolves every label it derives from a key through the Rails i18n conventions you already know. Translating the UI is a matter of YAML. Nothing in a definition or a policy changes.
 
 ## The strings come from YAML
 
@@ -29,7 +28,7 @@ en:
       "false": "Off"
 ```
 
-That one move covers renaming "On" to "Active" in English and translating it to another language. There is no second mechanism to learn for the second case.
+That one move covers rewording the default "Yes" and "No" in English and translating them to another language. There is no second mechanism to learn for the second case.
 
 ## The labels you never wrote translate too
 
@@ -82,7 +81,7 @@ The Stimulus controllers bundled with the gem read their strings from a JSON blo
 
 ## Ship a half-translated locale
 
-You do not have to finish a language before you use it. The dummy demo translates the blog-posts screen and leaves the rest of the app, the dates, and Rodauth's own flashes to fall back to English through `config.i18n.fallbacks`. That matters more than it sounds: the test environment turns on `raise_on_missing_translations`, so a page under a half-done locale would otherwise blow up on the first key you had not reached yet. With fallbacks on, a found-via-fallback string is not missing. Translate the screens your users live on first, ship it, and fill in the rest as you go.
+You do not have to finish a language before you use it. The dummy demo translates the blog-posts screen and leaves the rest of the app, the dates, and Rodauth's own flashes to fall back to English through `config.i18n.fallbacks`. That matters more than it sounds: the dummy's test environment turns on `raise_on_missing_translations`, as many apps do, so a page under a half-done locale would otherwise blow up on the first key you had not reached yet. With fallbacks on, a found-via-fallback string is not missing. Translate the screens your users live on first, ship it, and fill in the rest as you go.
 
 ## Adding a language
 

data/docs/getting-started/installation.md

@@ -9,7 +9,7 @@ rails new myapp -a propshaft -j esbuild -c tailwind \
   -m https://radioactive-labs.github.io/plutonium-core/templates/plutonium.rb
 ```
 
-This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium — plus Rodauth auth, asset pipeline, and initial migrations.
+This sets up Rails with Propshaft, esbuild, TailwindCSS, and Plutonium, plus Rodauth auth, asset pipeline, and initial migrations.
 
 After the template completes:
 
@@ -62,7 +62,7 @@ For account options and customization, see [Reference › Auth](/reference/auth/
 rails generate pu:core:assets
 ```
 
-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).
+Installs npm packages, creates `tailwind.config.js` extending Plutonium's config, imports Plutonium CSS, registers Stimulus controllers (`registerControllers(application)`, which your own JS bundle must keep), and points `config.assets.stylesheet` / `script` at your `application` bundles. Until then the app serves the gem's prebuilt CSS and JS, so it is required for custom CSS, brand colors or your own Stimulus controllers. It needs `app/assets/stylesheets/application.tailwind.css` and `app/javascript/controllers/index.js` (an app created with `-j esbuild -c tailwind` plus Stimulus). See [Reference › UI › Assets](/reference/ui/assets) and [Guides › Theming](/guides/theming).
 
 ## Verify
 
@@ -99,6 +99,6 @@ bin/dev
 
 ## Next steps
 
-- [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
+- [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,7 +118,7 @@ rails db:prepare
 
 ## Creating a 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).
+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 --public
@@ -149,9 +149,9 @@ Visit `http://localhost:3000/admin/blogging/posts`. You should see an empty post
 
 ![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):
+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) |
+| 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) |
 

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

@@ -14,7 +14,7 @@ Plutonium integrates Rodauth seamlessly with its portal system.
 
 ## Installing Rodauth
 
-Run the Plutonium Rodauth installer once per app — it creates the Rodauth app, plugin, and initializer:
+Run the Plutonium Rodauth installer once per app. It creates the Rodauth app, plugin, and initializer:
 
 ```bash
 rails generate pu:rodauth:install
@@ -24,7 +24,7 @@ rails generate pu:rodauth:install
 
 ## Creating an Account Type
 
-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:
+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
@@ -71,8 +71,8 @@ rails generate pu:pkg:portal admin --auth=admin --force
 
 This updates two files:
 
-- `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:
+- `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:
 
   ```ruby
   constraints Rodauth::Rails.authenticate(:admin) do
@@ -80,9 +80,9 @@ This updates two files:
   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.
+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.)
+(If you prefer not to regenerate, you can apply both edits by hand; they're shown above.)
 
 ## Testing Authentication
 
@@ -164,7 +164,7 @@ Now we can add the author relationship to our Post model. Generate a migration:
 rails generate migration AddUserToBloggingPosts user:belongs_to
 ```
 
-Update the migration to add the foreign key:
+Update the migration to add the foreign key (keep the `Migration[x.y]` version Rails generated for your app):
 
 ```ruby
 class AddUserToBloggingPosts < ActiveRecord::Migration[8.0]

data/docs/getting-started/tutorial/04-authorization.md

@@ -28,8 +28,13 @@ Let's implement basic CRUD permissions:
 
 ```ruby
 class Blogging::PostPolicy < Blogging::ResourcePolicy
-  # Anyone can view published posts
+  # Anyone can open the list; relation_scope (below) decides which posts it holds
   def read?
+    true
+  end
+
+  # A single post: published, or your own
+  def show?
     record.published? || owner?
   end
 
@@ -56,6 +61,8 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
 end
 ```
 
+`read?` also backs `index?`, which is checked against the `Blogging::Post` class rather than a post, so `record.published?` there would raise `NoMethodError` on the list page. Record-state checks go in `show?`, `update?` and `destroy?`, which always receive the post.
+
 ## Understanding the Policy Context
 
 Inside a policy, you have access to:
@@ -63,13 +70,13 @@ Inside a policy, you have access to:
 | Accessor | Description |
 |----------|-------------|
 | `user` | The current authenticated user |
-| `record` | The resource being authorized |
+| `record` | The resource being authorized (the resource class on collection routes such as index and new) |
 | `entity_scope` | Parent record for scoping (e.g., Organization in multi-tenant apps) |
 
 ```ruby
 def some_permission?
   user          # => Current user (from authentication)
-  record        # => The Post instance being checked
+  record        # => The Post instance being checked (Blogging::Post on index/new)
   entity_scope  # => Parent record for multi-tenancy (or nil)
 end
 ```
@@ -101,6 +108,12 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
       [:title] # Limited view for unpublished posts
     end
   end
+
+  # The table is built from the class, not a post, so this must not touch `record`
+  # (without it, index falls back to permitted_attributes_for_read and raises)
+  def permitted_attributes_for_index
+    [:title, :published, :created_at, :user]
+  end
 end
 ```
 
@@ -108,7 +121,7 @@ end
 
 Control which records appear in listings:
 
-`relation_scope` is a macro — it takes a block. Writing it as a plain instance
+`relation_scope` is a macro: it takes a block. Writing it as a plain instance
 method (`def relation_scope(relation)`) overrides nothing and your scoping is
 silently ignored, so Plutonium raises if you try.
 
@@ -148,6 +161,10 @@ class AdminPortal::Blogging::PostPolicy < ::Blogging::PostPolicy
     true
   end
 
+  def show?
+    true
+  end
+
   def update?
     true
   end

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

@@ -79,11 +79,11 @@ end
 
 ## Testing the Action
 
-Open any unpublished post and click **Actions** in the top-right — the "Publish Post" item appears with its Tabler icon:
+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:
+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)
 

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

@@ -13,8 +13,11 @@ Nested resources are resources that belong to a parent resource. In our blog:
 
 ```bash
 rails generate pu:res:scaffold Comment body:text user:belongs_to Blogging/Post:belongs_to --dest=blogging
+rails db:prepare
 ```
 
+Run the migration before connecting the resource to a portal: `pu:res:conn` reads the table's columns to seed the policy's attribute lists.
+
 ## Setting Up the Association
 
 Update the Post model to add the `has_many` association:
@@ -69,11 +72,11 @@ class Blogging::PostPolicy < Blogging::ResourcePolicy
 end
 ```
 
-The post show page now has tabs — **Details** and **Comments** — driven by the associations you permit:
+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:
+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)
 

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

@@ -168,11 +168,11 @@ 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)`:
+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):
+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)
 

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