Plutonium: Router & Bootstrapper

Entry point for all Plutonium work. Does three things:

1. Surfaces the most expensive mistakes up front (🚨 below).
2. Tells you which skills to load for greenfield work.
3. Maps specific "about to…" actions to the right targeted skill (router table).

🚨 Critical (read first)

• Plutonium is generator-driven. Almost every file you'd hand-write has a pu:* generator. Hand-written files drift from conventions and break future generator runs.
• For greenfield (new app, substantial new feature, first resource in a new domain), load the bootstrap bundle below before writing code.
• For targeted edits: use the router table to jump to the right skill.
• For anything touching tenant scoping: load plutonium-tenancy. Don't reach for where(organization: ...) in a policy; fix the model instead.
• Unattended execution: always pass --dest=, --force (when re-running meta-generators), --auth=, --skip-bundle, --quiet so generators don't block on prompts. See Unattended execution.
• Inspect before you act. Every targeted skill now opens with a CHECK gate: read the relevant files yourself before scaffolding or editing. Don't ask the user to describe their app when you can read it.

The mental model (read once: it decides what you should write)

Plutonium applies Rails' bargain (follow the convention and the framework carries you; reach for an escape hatch when you need one) to the layer above CRUD: auth, authorization, multi-tenancy, admin UI, business operations. Four consequences change what you should actually type.

1. Everything is derived from something you already declared

Not "defaults someone picked for you": computed from existing declarations:

Derived	From
Field types, required markers, select choices	model columns, associations, attachments, enums, and validations (presence: true → required; inclusion: → select choices)
A collection's preloads (index, kanban, export)	the policy's permitted field set; there is no includes list to write or maintain
Tenant scope	your associations: direct belongs_to, then has_one/has_one :through, then reverse has_many
Action type (record / bulk / resource)	whether the interaction declares :resource, :resources, or neither
An association input's typeahead	the target resource's own search block
CRUD, nested and action routes	one register_resource line

⇒ Declare only what differs. A field :title matching the detected type is dead code, and one more line to fall out of step when the column changes. This is the single most common way generated-looking code goes wrong.

2. Definition and policy answer different questions

• Definition = how a field renders.
• Policy = whether it appears at all.

"Only admins see this field" is permitted_attributes_for_*. Never a definition declaration, and never a condition: (that only hides UI; the route stays live).

3. Overrides are plain Ruby inheritance

AdminPortal::PostDefinition < ::PostDefinition, and the same for policies and controllers. App-level default, portal-level subclass. No registry of overrides, no precedence DSL, no merge semantics, so "why does this field show here but not there" is always readable as a class hierarchy.

4. Climb the escape-hatch ladder only as far as the problem requires

1. Change an option: input :content, as: :markdown
2. Render inline: display :priority do |f| … end (a block, instance_execed in Phlex, emits markup directly and gives you f.object)
3. Write a component: a field component (subclasses the Phlexi base) plugs into as:; anything with its own constructor goes through a block (display :card do |field| … end)
4. Implement a hook: controller hooks instead of reopening create/update; page render_before_* / render_after_* instead of view_template
5. Replace the page: view_template on the nested class, or an ERB view at the controller path (ERB wins when both exist)

Reaching for rung 5 on a rung-1 problem is how you end up owning breadcrumbs, the header and turbo frame wiring you never meant to touch.

Underneath all of it, it stays Rails. Models are plain ActiveRecord, controllers inherit from Rails controllers, views resolve through Rails view paths. A Plutonium resource and a hand-written controller coexist in one app.

✅ Orient before you route (CHECK: read the app, don't assume)

A one-line request rarely says whether this is a new app, a half-built one, or a multi-tenant one, and those change which path you take. Spend 30 seconds reading the app before loading a bundle or running anything:

Read	Tells you
git log --oneline | head; is there a populated Gemfile + app/?	Greenfield vs existing → install path (plutonium-app: base.rb, never plutonium.rb on an existing app)
grep Gemfile for plutonium; ls config/packages.rb	Already installed? → skip install
ls packages/	What portals / feature packages already exist
Does any model belongs_to an org/team/tenant?	Multi-tenant → load plutonium-tenancy before declaring scoping

This is the global "look before you leap"; each targeted skill carries its own ASK/CHECK gate for the specifics. Never run an installer or scaffold from a one-line request without first reading what's already there.

The skills

Skill	Covers
[[plutonium-app]]	Installation, packages (feature + portal), portal engines, mounting, register_resource (including singular and custom routes), pu:res:conn
[[plutonium-resource]]	The resource itself: pu:res:scaffold, field types, model layer (Plutonium::Resource::Record, has_cents, SGID, routing), definition layer (fields/inputs/displays/columns, search/filters/scopes/sorting, custom actions, bulk actions, index views, page customization)
[[plutonium-behavior]]	Controllers (hooks, key methods, presentation), policies (action methods, permitted_attributes_for_*, permitted_associations), interactions (structure, outcomes, chaining, URL generation)
[[plutonium-async-interactions]]	Async interactions: async, the Run STI model, failure policies (halt/continue/transactional), authorization re-derivation at perform time, registering AsyncRun as a resource (progress page + running banner), scheduling ReapJob
[[plutonium-ui]]	Page classes, forms, displays, tables, custom Phlex components, layouts, modals & tabs, Tailwind config, Stimulus, design tokens, .pu-* classes, Phlexi themes
[[plutonium-kanban]]	kanban do…end DSL in a Definition, columns, card_fields, position_on, realtime, column actions, kanban_move? policy, quick-add, static vs dynamic boards
[[plutonium-dashboard]]	Dashboards, Plutonium::Dashboard::Base, metric / chart / card, register_dashboard, lazy turbo-frame cards, refresh, condition:, authorize?, pu:dashboard
[[plutonium-auth]]	Rodauth install, account types (basic / admin / SaaS), profile resource, security section
[[plutonium-tenancy]]	Entity scoping (associated_with, default_relation_scope, three model shapes), nested resources, invites
[[plutonium-testing]]	pu:test:install, pu:test:scaffold, ResourceCrud/ResourcePolicy/ResourceDefinition/ResourceModel/NestedResource/PortalAccess/ResourceInteraction, AuthHelpers
[[plutonium-wizard]]	Multi-step flows: the wizard DSL (step/review/using:/condition:, per-step on_submit/persist/on_rollback, execute), anchoring & resume, one-time wizards + gate, registration (wizard macro + register_wizard), storage/config + SweepJob

Greenfield bootstrap bundle

Triggers: installing Plutonium, building a new app, adding the first resource in a new domain, setting up a new portal or package, "build me a Y app", "set up X from scratch".

Load these before writing code:

1. plutonium-app: install, portals, packages, routes.
2. plutonium-resource: scaffold, model, definition (the bulk of the work).
3. plutonium-behavior: controllers, policies, interactions.
4. plutonium-tenancy: only if multi-tenant; load before declaring entity scoping.

Add when relevant:

• plutonium-auth for login / accounts / profile.
• plutonium-ui for custom pages, forms, components, or theming.
• plutonium-testing when scaffolding tests.

Router table

About to…	Load
Install Plutonium, create a portal or package, mount engines, register routes (incl. singular / custom routes)	[[plutonium-app]]
Run pu:res:scaffold, pick field types, set scaffold options	[[plutonium-resource]]
Edit a model, add associations, use has_cents, override to_param / to_label	[[plutonium-resource]]
Edit a definition, fields, inputs, displays, columns, search, filters, scopes, custom actions, bulk actions, index views, modal/slideover, page titles	[[plutonium-resource]]
Override a controller action, hook, redirect, or resource_params	[[plutonium-behavior]]
Write relation_scope, permitted_attributes_for_*, permitted_associations, action methods, or any policy override	[[plutonium-behavior]] (+ [[plutonium-tenancy]] if scoping)
Write an interaction class for business logic	[[plutonium-behavior]]
Make a bulk/long-running interaction async (async), or schedule the stalled-run reaper	[[plutonium-async-interactions]]
Scope a model to a tenant, write associated_with, set portal entity strategy	[[plutonium-tenancy]]
Configure parent/child nested routes, custom parent resolution	[[plutonium-tenancy]]
Set up user invitations or entity membership	[[plutonium-tenancy]]
Build or customize a kanban board view, kanban do…end, columns, card_fields, position_on, realtime, column actions, kanban_move? policy	[[plutonium-kanban]]
Build a dashboard, KPI overview or chart page, pu:dashboard, metric / chart / card, register_dashboard, refresh, per-card conditions	[[plutonium-dashboard]]
Build a custom page (override ShowPage/IndexPage/NewPage/EditPage), custom form, custom display, custom table, custom Phlex component	[[plutonium-ui]]
Configure Tailwind, register Stimulus controllers, edit design tokens, theme forms/displays/tables, write a custom layout	[[plutonium-ui]]
Install Rodauth, set up accounts, configure login flow, add the profile resource	[[plutonium-auth]]
Write tests for a resource, run pu:test:scaffold, include Plutonium::Testing::* concerns	[[plutonium-testing]]
Build a multi-step flow, onboarding, checkout, branching create, register a wizard / register_wizard, gate a one-time wizard	[[plutonium-wizard]]

Resource architecture at a glance

A resource is four cooperating layers; Plutonium auto-fills defaults from the model, so you only declare overrides:

Layer	File	Purpose
Model	app/models/post.rb	Data, validations, associations
Definition	app/definitions/post_definition.rb	UI, fields, filters, actions
Policy	app/policies/post_policy.rb	Authorization: who, what
Controller	app/controllers/posts_controller.rb	Request handling (rarely edited; use hooks)

Plus one optional fifth layer:

Layer	File	Purpose
Interaction	app/interactions/publish_post_interaction.rb	Business logic for custom actions

Generator catalog

Every Plutonium generator is discoverable via rails g pu:<tab>. Always pass --dest= to skip prompts.

Generator	Purpose	Skill
pu:core:install	Initial Plutonium setup	plutonium-app
pu:core:assets	Custom Tailwind + Stimulus toolchain	plutonium-ui
pu:res:scaffold NAME field:type ...	New resource (model, migration, controller, policy, definition)	plutonium-resource
pu:res:conn RESOURCE --dest=PORTAL	Connect resource to a portal	plutonium-app
pu:pkg:package NAME	Feature package	plutonium-app
pu:pkg:portal NAME --auth=... --scope=...	Portal package	plutonium-app
pu:rodauth:install	Install Rodauth base	plutonium-auth
pu:rodauth:account NAME	Basic Rodauth account	plutonium-auth
pu:rodauth:admin NAME	Hardened admin account (2FA, lockout, audit)	plutonium-auth
pu:saas:setup --user ... --entity ...	Meta: user + entity + membership + portal + profile + welcome + invites	plutonium-auth + plutonium-tenancy
pu:saas:user / :entity / :membership / :portal / :welcome	Individual SaaS pieces	plutonium-auth + plutonium-app
pu:profile:install / :setup / :conn	Profile resource + security section	plutonium-auth
pu:invites:install	User invitations package	plutonium-tenancy
pu:invites:invitable NAME	Mark a model as invitable	plutonium-tenancy
pu:eject:layout	Eject base layout for customization	plutonium-ui
pu:eject:shell	Eject topbar/sidebar partials	plutonium-ui
pu:test:install	Install Plutonium::Testing scaffolding	plutonium-testing
pu:test:scaffold NAME --portals=...	Scaffold integration tests	plutonium-testing
pu:dashboard NAME --dest=PORTAL [--at=/]	Dashboard class + register_dashboard route	plutonium-dashboard
pu:skills:sync	Sync Plutonium Claude skills into the project	(this skill)

Unattended execution

Plutonium generators are interactive by default. For scripts, agents, or CI:

Flag	Generators	Purpose
--dest=main_app / --dest=<package>	pu:res:scaffold, pu:res:conn, package-targeted generators	Skip "select destination" prompt
--force	any	Overwrite conflicting files (required when re-running pu:saas:setup or meta-generators)
--auth=<account> / --public / --byo	pu:pkg:portal	Skip auth-type prompt
--skip-bundle	gem-installing generators	Avoid mid-run bundle install
--quiet	most	Reduce output noise

Meta-generators (pu:saas:setup) propagate flags to the generators they chain. Always pass --force when re-running a meta-generator on an app that already has some of its outputs.

Workflow summary

1. Load the bootstrap bundle (or the targeted skill from the router table).
2. Generate: rails g pu:res:scaffold Model field:type ... --dest=main_app.
3. Migrate: rails db:prepare.
4. Connect: rails g pu:res:conn Model --dest=portal_name.
5. Customize: edit definition / policy as needed.
6. Verify: hit the route in the browser.