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](#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:

⇒ 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 permittedattributesfor_*. 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, as: :phlexi_render, with: ->(value, attrs) do … end
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 renderbefore / renderafter 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:

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

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

Resource architecture at a glance

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

Plus one optional fifth layer:

Generator catalog

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

Unattended execution

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

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.