plutonium 0.62.2 → 0.63.0

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

@@ -0,0 +1,293 @@
+<template>
+  <section class="pu-section">
+    <div class="pu-section-inner">
+      <h2 class="pu-section-title">More than CRUD.</h2>
+      <p class="ft-sub">
+        Five features other frameworks make you build yourself.
+        All declarative. All policy-aware.
+      </p>
+
+      <div class="ft-grid" :style="gridStyle">
+        <template v-for="f in features" :key="f.id">
+          <button
+            class="ft-head"
+            :class="{ 'ft-head--on': selected === f.id }"
+            :aria-expanded="selected === f.id"
+            :aria-controls="selected === f.id ? `ft-panel-${f.id}` : undefined"
+            @click="selected = f.id"
+          >
+            <span class="ft-head-text">
+              <b>{{ f.name }}</b>
+              <small>{{ f.hook }}</small>
+            </span>
+            <IconChevronDown class="ft-chev" :size="16" :stroke-width="2" aria-hidden="true" />
+          </button>
+
+          <div v-if="selected === f.id" :id="`ft-panel-${f.id}`" class="ft-body">
+            <div class="ft-caption">{{ f.file }}</div>
+            <pre class="ft-code" v-html="f.code"></pre>
+            <img v-if="f.shot" :src="withBase(f.shot)" :alt="f.alt" class="ft-shot pu-zoomable" />
+            <div class="ft-foot">
+              <span class="ft-policy">
+                <IconShieldCheck :size="14" :stroke-width="2" aria-hidden="true" /> {{ f.policy }}
+              </span>
+              <a class="ft-link" :href="f.link">Read the guide →</a>
+            </div>
+          </div>
+        </template>
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { ref } from "vue"
+import { withBase } from "vitepress"
+import { IconChevronDown, IconShieldCheck } from "@tabler/icons-vue"
+
+const features = [
+  {
+    id: "actions",
+    name: "Actions & interactions",
+    hook: "Business logic with auto-generated UI",
+    file: "packages/blogging/app/definitions/blogging/post_definition.rb",
+    code: `<span class="k">class</span> Blogging::PostDefinition <span class="k">&lt;</span> Blogging::ResourceDefinition
+  <span class="m">scope</span> <span class="s">:published</span>
+  <span class="m">scope</span> <span class="s">:drafts</span>
+  <span class="m">scope</span> <span class="s">:archived</span>
+
+  <span class="m">action</span> <span class="s">:publish</span>, interaction: Blogging::PublishPost
+  <span class="m">action</span> <span class="s">:archive</span>, interaction: Blogging::ArchivePost
+<span class="k">end</span>
+
+<span class="c"># packages/blogging/app/interactions/blogging/publish_post.rb</span>
+<span class="k">class</span> Blogging::PublishPost <span class="k">&lt;</span> Blogging::ResourceInteraction
+  <span class="m">presents</span> label: <span class="s">"Publish Post"</span>, icon: Phlex::TablerIcons::Send
+
+  <span class="m">attribute</span> <span class="s">:resource</span>
+
+  <span class="k">def</span> <span class="f">execute</span>
+    resource.update!(status: <span class="s">:published</span>)
+    succeed(resource).with_message(<span class="s">"Post published successfully!"</span>)
+  <span class="k">end</span>
+<span class="k">end</span>
+
+<span class="c"># packages/blogging/app/policies/blogging/post_policy.rb</span>
+<span class="k">class</span> Blogging::PostPolicy <span class="k">&lt;</span> Blogging::ResourcePolicy
+  <span class="k">def</span> <span class="f">publish?</span> = record.draft?
+  <span class="k">def</span> <span class="f">archive?</span> = record.published?
+<span class="k">end</span>`,
+    shot: "/images/home/tour-actions.png",
+    alt: "Blog posts table with the row actions menu open — Publish Post appears on the draft row only",
+    policy: "No publish? policy method, no button — it disappears, it doesn't disable.",
+    link: "/plutonium-core/guides/custom-actions",
+  },
+  {
+    id: "tenancy",
+    name: "Multi-tenancy & nesting",
+    hook: "Scoping, invites, nested resources",
+    file: "packages/org_portal/lib/engine.rb",
+    code: `<span class="k">module</span> OrgPortal
+  <span class="k">class</span> Engine <span class="k">&lt;</span> Rails::Engine
+    <span class="k">include</span> Plutonium::Portal::Engine
+
+    config.after_initialize <span class="k">do</span>
+      <span class="m">scope_to_entity</span> ::Organization, strategy: <span class="s">:path</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span>
+
+<span class="c"># → /org/1 — every count on this dashboard is scoped to organization 1</span>`,
+    shot: "/images/home/tour-tenancy.png",
+    alt: "Tenant-scoped portal dashboard where every resource card counts only the current organization's records",
+    policy: "Every query flows through the entity scope — no default_scope hacks.",
+    link: "/plutonium-core/guides/multi-tenancy",
+  },
+  {
+    id: "wizards",
+    name: "Wizards",
+    hook: "Multi-step flows with branching & resume",
+    file: "app/wizards/onboard_organization_wizard.rb",
+    code: `<span class="k">class</span> OnboardOrganizationWizard <span class="k">&lt;</span> Plutonium::Wizard::Base
+  <span class="m">presents</span> label: <span class="s">"Onboard an organization"</span>,
+    description: <span class="s">"Set up a workspace for your team — a few quick steps and you're in."</span>
+
+  <span class="m">step</span> <span class="s">:identity</span>, description: <span class="s">"Tell us who you are — this names the workspace."</span> <span class="k">do</span>
+    <span class="m">attribute</span> <span class="s">:name</span>, <span class="s">:string</span>
+    <span class="m">attribute</span> <span class="s">:plan</span>, <span class="s">:string</span>
+    <span class="m">attribute</span> <span class="s">:budget</span>, <span class="s">:decimal</span>
+    <span class="m">input</span> <span class="s">:plan</span>, as: <span class="s">:select</span>, choices: [[<span class="s">"Free"</span>, <span class="s">"free"</span>], [<span class="s">"Pro"</span>, <span class="s">"pro"</span>], [<span class="s">"Enterprise"</span>, <span class="s">"enterprise"</span>]]
+    <span class="m">input</span> <span class="s">:budget</span>, as: <span class="s">:currency</span>, unit: <span class="s">"$"</span>
+    <span class="m">validates</span> <span class="s">:name</span>, presence: <span class="k">true</span>
+
+    <span class="m">form_layout</span> <span class="k">do</span>
+      <span class="m">section</span> <span class="s">:basics</span>, <span class="s">:name</span>, <span class="s">:plan</span>, <span class="s">:budget</span>, label: <span class="s">"The basics"</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+
+  <span class="m">step</span> <span class="s">:details</span> <span class="k">do</span>
+    <span class="m">attribute</span> <span class="s">:note</span>, <span class="s">:string</span>
+    <span class="m">input</span> <span class="s">:note</span>, as: <span class="s">:textarea</span>
+  <span class="k">end</span>
+
+  <span class="m">step</span> <span class="s">:profile</span>, using: KitchenSink, fields: [<span class="s">:description</span>, <span class="s">:tier</span>]
+
+  <span class="m">step</span> <span class="s">:members</span> <span class="k">do</span>
+    <span class="m">structured_input</span> <span class="s">:invites</span>, repeat: <span class="n">5</span> <span class="k">do</span> |f|
+      f.<span class="m">input</span> <span class="s">:email</span>
+      f.<span class="m">input</span> <span class="s">:role</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+
+  <span class="m">review</span> label: <span class="s">"Review"</span>
+
+  <span class="k">def</span> <span class="f">execute</span>
+    org = Organization.create!(name: data.identity.name)
+    succeed(org).with_message(<span class="s">"Organization onboarded"</span>)
+  <span class="k">end</span>
+<span class="k">end</span>`,
+    shot: "/images/home/tour-wizard.png",
+    alt: "Wizard step page — numbered stepper with Identity, Details, Profile, Members, and Review stops, and a typed step form",
+    policy: "Steps validate per-screen; the built-in review step gates the finish.",
+    link: "/plutonium-core/guides/wizards",
+  },
+  {
+    id: "kanban",
+    name: "Kanban boards",
+    hook: "Drag-drop boards from one block",
+    file: "app/definitions/task_definition.rb",
+    code: `<span class="m">kanban</span> <span class="k">do</span>
+  <span class="m">card_fields</span> header: <span class="s">:title</span>, meta: [<span class="s">:status</span>]
+
+  <span class="m">column</span> <span class="s">:todo</span>, role: <span class="s">:backlog</span>,
+    scope: -&gt; { where(status: <span class="s">"todo"</span>) },
+    on_enter: -&gt;(task) { task.update!(status: <span class="s">"todo"</span>) }
+
+  <span class="m">column</span> <span class="s">:doing</span>, wip: <span class="n">3</span>,
+    scope: -&gt; { where(status: <span class="s">"doing"</span>) },
+    on_enter: -&gt;(task) { task.update!(status: <span class="s">"doing"</span>) }
+
+  <span class="m">column</span> <span class="s">:done</span>, role: <span class="s">:done</span>, accepts: [<span class="s">:doing</span>],
+    scope: -&gt; { where(status: <span class="s">"done"</span>) },
+    on_enter: <span class="s">:mark_done!</span> <span class="k">do</span>
+    <span class="m">action</span> <span class="s">:archive_all</span>, interaction: ArchiveTasksInteraction, on: <span class="s">:all</span>, label: <span class="s">"Archive all"</span>
+  <span class="k">end</span>
+<span class="k">end</span>`,
+    shot: "/images/home/tour-kanban.png",
+    alt: "Kanban board with Todo, Doing, and Done columns — WIP limit on Doing, quick-add on Todo, and an Archive all column action on Done",
+    policy: "Columns lock and drags are rejected server-side when kanban_move? says no.",
+    link: "/plutonium-core/guides/kanban",
+  },
+  {
+    id: "async",
+    name: "Async interactions",
+    hook: "Bulk work that outlives the request",
+    file: "packages/blogging/app/interactions/blogging/archive_posts.rb",
+    code: `<span class="k">class</span> Blogging::ArchivePosts <span class="k">&lt;</span> Blogging::ResourceInteraction
+  <span class="m">presents</span> label: <span class="s">"Archive"</span>, icon: Phlex::TablerIcons::Archive
+
+  <span class="m">attribute</span> <span class="s">:resources</span>        <span class="c"># bulk — perform_on runs once per record</span>
+  <span class="m">attribute</span> <span class="s">:reason</span>, <span class="s">:string</span>
+
+  <span class="m">async</span> <span class="k">do</span>
+    <span class="m">on_failure</span> <span class="s">:continue</span>      <span class="c"># :halt (default) | :continue | :transactional</span>
+
+    <span class="k">def</span> <span class="f">perform_on</span>(post)
+      post.archive!(reason: options[<span class="s">"reason"</span>])
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span>
+
+<span class="c"># → persists a run, enqueues it, redirects to its live progress page</span>`,
+    shot: "/images/home/tour-async.png",
+    alt: "The run's progress page mid-flight — a Running badge, a progress bar at 27 of 50 targets, and the run's type, target type and initiator",
+    policy: "Permissions are re-derived when the job runs, never replayed from dispatch.",
+    link: "/plutonium-core/reference/behavior/async-interactions",
+  },
+]
+
+const selected = ref(features[0].id)
+
+// One explicit row per feature head, with the last absorbing the panel's extra
+// height. Derived from features.length — a hardcoded count silently drops any
+// head past it into an implicit row below the grid.
+const gridStyle = { gridTemplateRows: `repeat(${features.length - 1}, auto) 1fr` }
+</script>
+
+<style scoped>
+.ft-sub { color: var(--pu-text-muted); font-size: 15px; margin: -16px 0 28px; }
+
+.ft-grid {
+  display: grid;
+  grid-template-columns: 260px 1fr;
+  /* grid-template-rows is set inline from features.length — see gridStyle */
+  column-gap: 28px;
+  align-items: start;
+}
+.ft-head {
+  grid-column: 1;
+  display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  width: 100%; text-align: left; cursor: pointer;
+  background: transparent; font-family: inherit;
+  border: 0; border-left: 3px solid transparent;
+  border-bottom: 1px solid var(--pu-border-soft);
+  padding: 14px 16px;
+  transition: border-color 0.15s ease, background 0.15s ease;
+}
+.ft-head:hover { background: var(--pu-bg-band); }
+.ft-head--on { border-left-color: var(--pu-accent); background: var(--pu-bg-band); }
+.ft-head-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.ft-head b { font-size: 14.5px; font-weight: 600; color: var(--pu-text); }
+.ft-head--on b { color: var(--pu-accent); }
+.ft-head small { font-size: 12px; color: var(--pu-text-faint); }
+.ft-chev { color: var(--pu-text-faint); flex-shrink: 0; display: none; }
+
+.ft-body { grid-column: 2; grid-row: 1 / -1; min-width: 0; }
+.ft-caption {
+  font-size: 11px; letter-spacing: 0.05em;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  color: #8b949e; background: #161b22;
+  border: 1px solid #30363d; border-bottom: 0;
+  border-radius: 8px 8px 0 0; padding: 8px 14px;
+  overflow-wrap: anywhere;
+}
+.ft-code {
+  background: var(--pu-bg-dark); color: var(--pu-term-text);
+  border-radius: 0 0 8px 8px; margin: 0; padding: 14px 16px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12.5px; line-height: 1.6; overflow-x: auto; white-space: pre;
+}
+.ft-code :deep(.k) { color: #ff7b72; }
+.ft-code :deep(.s) { color: #a5d6ff; }
+.ft-code :deep(.m) { color: #d2a8ff; }
+.ft-code :deep(.f) { color: #d2a8ff; }
+.ft-code :deep(.n) { color: #79c0ff; }
+.ft-code :deep(.c) { color: #8b949e; }
+
+.ft-shot {
+  display: block; width: 100%; height: auto; margin-top: 14px;
+  border: 1px solid var(--pu-border-soft); border-radius: 8px;
+}
+.ft-foot {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 12px; flex-wrap: wrap; margin-top: 12px;
+}
+.ft-policy {
+  display: inline-flex; align-items: center; gap: 6px;
+  font-size: 12.5px; color: var(--pu-text-muted);
+}
+.ft-policy svg { color: var(--pu-success-fg); flex-shrink: 0; }
+.ft-link {
+  font-size: 13px; font-weight: 500; color: var(--pu-accent);
+  text-decoration: none; white-space: nowrap;
+}
+.ft-link:hover { text-decoration: underline; }
+
+@media (max-width: 768px) {
+  .ft-grid { display: block; }
+  .ft-head { border: 1px solid var(--pu-border-soft); border-left-width: 3px; border-radius: 6px; margin-bottom: 8px; }
+  .ft-chev { display: block; transition: transform 0.15s ease; }
+  .ft-head--on .ft-chev { transform: rotate(180deg); }
+  .ft-body { margin: 4px 0 16px; }
+}
+</style>

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

@@ -10,8 +10,8 @@
           Convention over configuration, extended to everything you keep rebuilding.
         </p>
         <p class="home-hero-pillars">
-          <b>CRUD.</b> <b>Auth.</b> <b>Authorization.</b> <b>Multi-tenancy.</b>
-          <b>Admin portals.</b> <b>Search, filters, bulk actions.</b>
+          <!-- keep the bolds on one source line: Vue drops whitespace-only nodes containing newlines -->
+          <b>CRUD.</b> <b>Auth.</b> <b>Authorization.</b> <b>Multi-tenancy.</b> <b>Wizards.</b> <b>Kanban.</b> <b>Admin portals.</b> <b>Search, filters, bulk actions.</b>
           All generated. All customizable. All Rails.
         </p>
         <div class="home-hero-ctas">
@@ -23,7 +23,7 @@
 <span class="dim">      create  packages/admin_portal/...</span>
 <span class="prompt">$</span> rails g pu:res:scaffold Post title:string body:text published_at:datetime --dest=main_app
 <span class="dim">      create  app/models/post.rb</span>
-<span class="dim">      create  app/resource_registries/post_definition.rb</span>
+<span class="dim">      create  app/definitions/post_definition.rb</span>
 <span class="prompt">$</span> rails g pu:res:conn Post --dest=admin_portal
 <span class="dim">      ✓ Connected Post to AdminPortal</span>
 <span class="prompt">$</span> <span class="pu-term-cursor"></span></pre>

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

@@ -30,6 +30,14 @@ const cats = [
     { name: "Custom & bulk actions", desc: "Resource-scoped interactions",
       link: "/plutonium-core/guides/custom-actions" },
   ]},
+  { name: "Workflows", items: [
+    { name: "Wizards", desc: "Multi-step flows with branching & resume",
+      link: "/plutonium-core/guides/wizards" },
+    { name: "Kanban boards", desc: "Drag-drop boards from one block",
+      link: "/plutonium-core/guides/kanban" },
+    { name: "Interactions", desc: "Business logic with auto-generated UI",
+      link: "/plutonium-core/guides/custom-actions" },
+  ]},
   { name: "App structure", items: [
     { name: "Portals", desc: "Themed, mountable engines",
       link: "/plutonium-core/reference/app/portals" },

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

@@ -19,6 +19,7 @@
             <span><b>Full CRUD</b></span>
             <span><b>+ Search</b></span>
             <span><b>+ Filters</b></span>
+            <span><b>+ Custom actions</b></span>
             <span><b>+ Bulk actions</b></span>
           </div>
         </div>

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

@@ -0,0 +1,84 @@
+<template>
+  <section class="pu-section pu-section--band">
+    <div class="pu-section-inner">
+      <h2 class="pu-section-title">Built on Rails. Wired for shipping.</h2>
+
+      <div class="wp-grid">
+        <div class="wp-card" v-for="p in pillars" :key="p.name">
+          <component :is="p.icon" class="wp-icon" :size="20" :stroke-width="1.75" />
+          <div class="wp-name">{{ p.name }}</div>
+          <div class="wp-desc">{{ p.desc }}</div>
+        </div>
+      </div>
+
+      <div class="wp-audiences">
+        <div class="wp-aud">
+          <div class="wp-aud-head">For Rails developers</div>
+          <p class="wp-aud-lede">The missing layer between Rails and the apps you keep building.</p>
+          <ul class="wp-aud-list">
+            <li><IconArrowRight class="wp-arr" :size="16" :stroke-width="2.25" aria-hidden="true" /><span>Convention extended to CRUD, policies, and portals</span></li>
+            <li><IconArrowRight class="wp-arr" :size="16" :stroke-width="2.25" aria-hidden="true" /><span>Generated code lives in your repo — edit anything</span></li>
+          </ul>
+        </div>
+        <div class="wp-aud wp-aud--right">
+          <div class="wp-aud-head">For founders &amp; teams</div>
+          <p class="wp-aud-lede">Skip the SaaS template debate. Plutonium turns Rails into a SaaS toolkit.</p>
+          <ul class="wp-aud-list">
+            <li><IconArrowRight class="wp-arr" :size="16" :stroke-width="2.25" aria-hidden="true" /><span>Admin panel, signup, and invites on day one</span></li>
+            <li><IconArrowRight class="wp-arr" :size="16" :stroke-width="2.25" aria-hidden="true" /><span>Multi-tenant scoping when you need it</span></li>
+          </ul>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { IconRoute, IconCode, IconBuildingSkyscraper, IconRobot, IconArrowRight } from "@tabler/icons-vue"
+
+const pillars = [
+  { icon: IconRoute, name: "Convention over configuration",
+    desc: "Extended to resources, policies, portals, and tenancy — not just routes and views." },
+  { icon: IconCode, name: "It's just Rails",
+    desc: 'Generated code lives in your repo. Edit it, override it, delete it. The “magic” is regular Ruby mixins you can read.' },
+  { icon: IconBuildingSkyscraper, name: "Multi-tenant ready",
+    desc: "Path or domain tenancy. Scoped relations. Invites and memberships out of the box." },
+  { icon: IconRobot, name: "AI-readable",
+    desc: "Predictable file layout and naming. Built-in skills teach AI assistants the patterns." },
+]
+</script>
+
+<style scoped>
+.wp-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; }
+.wp-card {
+  padding: 14px 16px; border: 1px solid var(--pu-border-soft); border-radius: 8px;
+  background: var(--pu-bg-light);
+}
+.wp-icon { color: var(--pu-accent); margin-bottom: 8px; display: block; }
+.wp-name { font-weight: 600; font-size: 14px; color: var(--pu-text); margin-bottom: 4px; line-height: 1.25; }
+.wp-desc { font-size: 12.5px; color: var(--pu-text-muted); line-height: 1.5; }
+
+.wp-audiences {
+  display: grid; grid-template-columns: 1fr 1fr; gap: 28px;
+  margin-top: 28px; padding-top: 24px; border-top: 1px solid var(--pu-border);
+}
+.wp-aud--right { border-left: 1px solid var(--pu-border); padding-left: 28px; }
+.wp-aud-head {
+  font-size: 11px; text-transform: uppercase; letter-spacing: 0.1em;
+  color: var(--pu-accent); font-weight: 600; margin-bottom: 6px;
+}
+.wp-aud-lede {
+  font-size: 16px; line-height: 1.35; font-weight: 500; color: var(--pu-text);
+  margin: 0 0 10px; letter-spacing: -0.01em;
+}
+.wp-aud-list { list-style: none; padding: 0; margin: 0; font-size: 14px; line-height: 1.6; color: var(--pu-text-muted); }
+.wp-aud-list li { display: flex; gap: 10px; align-items: flex-start; padding: 4px 0; }
+.wp-arr { color: var(--pu-accent); flex-shrink: 0; margin-top: 3px; }
+
+@media (max-width: 900px) { .wp-grid { grid-template-columns: repeat(2, 1fr); } }
+@media (max-width: 768px) {
+  .wp-audiences { grid-template-columns: 1fr; }
+  .wp-aud--right { border-left: none; padding-left: 0; border-top: 1px solid var(--pu-border); padding-top: 20px; }
+}
+@media (max-width: 480px) { .wp-grid { grid-template-columns: 1fr; } }
+</style>

data/docs/.vitepress/theme/index.ts

@@ -6,24 +6,28 @@ import "./custom.css"
 
 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 HomeFeatureTour from "./components/HomeFeatureTour.vue"
+import HomeWhyPlutonium from "./components/HomeWhyPlutonium.vue"
 import HomeInTheBox from "./components/HomeInTheBox.vue"
 import HomeCta from "./components/HomeCta.vue"
 import SectionLanding from "./components/SectionLanding.vue"
+import BlogIndex from "./components/BlogIndex.vue"
+import BlogMeta from "./components/BlogMeta.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("HomeFeatureTour", HomeFeatureTour)
+    app.component("HomeWhyPlutonium", HomeWhyPlutonium)
     app.component("HomeInTheBox", HomeInTheBox)
     app.component("HomeCta", HomeCta)
     app.component("SectionLanding", SectionLanding)
+    app.component("BlogIndex", BlogIndex)
+    app.component("BlogMeta", BlogMeta)
   },
   setup() {
     const route = useRoute()

data/docs/blog/association-inputs-post-signed-ids.md

@@ -0,0 +1,70 @@
+---
+title: "Plutonium association inputs post a signed id, not a database id"
+titleTemplate: "Plutonium Blog"
+date: 2026-09-28
+description: A select whose values are primary keys is a form the user can edit. Signed Global IDs make the tampered version fail instead of succeed.
+author: Stefan Froelich
+tags: [security, forms, rails]
+draft: true
+---
+
+# Plutonium association inputs post a signed id, not a database id
+
+<BlogMeta />
+
+Here is a form field every Rails app has:
+
+```erb
+<%= f.collection_select :author_id, User.all, :id, :name %>
+```
+
+It renders `<option value="42">`. The user opens devtools, changes 42 to 7, and submits. Whether that matters depends entirely on whether the controller thought to check, which is a sentence that should make you uncomfortable, because "whether someone thought to check" is not a security model.
+
+The usual defences are real but partial. Strong parameters decide *which* keys are allowed, not which values. A policy check on the parent record authorizes the edit, not the thing being pointed at. Scoping the collection you render controls what the select *offers*, and has no bearing on what the browser sends back.
+
+## What Plutonium sends instead
+
+Every association on a resource model gets Signed Global ID accessors, generated automatically:
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :user
+  has_many :tags
+end
+
+post.user_sgid                    # => "BAh7..."
+post.user_sgid = "BAh7..."        # locates and assigns from the SGID
+
+post.tag_sgids                    # => ["...", "..."]
+post.tag_sgids = [sgid1, sgid2]   # bulk replace
+```
+
+The association input posts the SGID. A Global ID carries the class as well as the id, and signing it means the server can tell whether the value it received is one it issued.
+
+Two consequences fall out.
+
+**Tampering fails instead of succeeding.** Editing the option value produces a signature that does not verify, so the assignment raises rather than silently pointing at record 7. The failure mode moves from "wrong data, no error" to "error, no data," which is the direction you want.
+
+**The class travels with the value.** `42` means nothing on its own; a Global ID says `gid://app/User/42`. A payload cannot smuggle a `Post` id into a field expecting a `User`, because the type is part of the signed value rather than an assumption the controller makes.
+
+## What it is not
+
+It is not authorization, and treating it as such is the mistake worth naming.
+
+An SGID proves the server issued this reference. It says nothing about whether *this* user may point at *that* record. A signed id you were legitimately given yesterday is still legitimately signed today, after your access was revoked.
+
+So the picker's options still come from `authorized_resource_scope`, which applies the target resource's own `relation_scope` and the current policy context. That is what decides which records a user may reference. The signature is a separate property: it stops the value being swapped for one that was never offered.
+
+Two mechanisms, two questions. What may you see, and is this the thing you were shown. Conflating them gets you a system that is careful about exactly one of them.
+
+## Why it can be automatic
+
+The reason this is on by default rather than an opt-in helper is that it costs the developer nothing. The accessors are generated from the associations already declared on the model, so there is no new declaration, no field-level configuration, and no way to forget it on the one form written in a hurry.
+
+That is the general shape of the useful kind of security default: not a feature you enable, but a thing that is already true because the framework could derive it from what you had already written. A defence you have to remember to apply is a defence with a failure rate equal to how often people are tired.
+
+## When you will notice it
+
+Mostly, never. The inputs render as ordinary selects with typeahead, and the values round-trip. You will notice on the day you look at a payload in the network tab and wonder why the author field contains `BAh7...` instead of a number.
+
+The answer is that a number would have been a request, and this is a receipt.

data/docs/blog/fix-the-model-not-the-policy.md

@@ -0,0 +1,122 @@
+---
+title: "Plutonium multi-tenancy: fix the model, not the policy"
+titleTemplate: "Plutonium Blog"
+date: 2026-08-27
+description: A tenant leak is usually a modelling problem wearing a query costume. Patching it with a where clause in a policy fixes one read and leaves the others open.
+author: Stefan Froelich
+tags: [multi-tenancy, authorization, rails]
+draft: true
+---
+
+# Plutonium multi-tenancy: fix the model, not the policy
+
+<BlogMeta />
+
+Most multi-tenancy bugs are not clever. They are a missing `where` on the one query somebody forgot, in the one place nobody looked.
+
+That is worth sitting with, because it tells you what kind of problem it is. If the fix for a leak is "add the filter here too," then the filter is not a property of your data. It is a habit, applied by hand, at every read, forever, by everyone who joins the team. Habits have a failure rate.
+
+Plutonium takes a different position: the relationship between a record and its tenant is a fact about your schema, and the framework should be able to *read* it rather than being told it repeatedly.
+
+## What you declare
+
+Once, on the portal:
+
+```ruby
+# packages/admin_portal/lib/engine.rb
+module AdminPortal
+  class Engine < ::Rails::Engine
+    include Plutonium::Portal::Engine
+
+    scope_to_entity Organization, strategy: :path
+  end
+end
+```
+
+Then you design your models the way you would have anyway:
+
+```ruby
+class Project < ApplicationRecord
+  belongs_to :organization
+end
+
+class Task < ApplicationRecord
+  belongs_to :project
+  has_one :organization, through: :project
+end
+```
+
+That is the whole setup. Every query in that portal is scoped, every create is associated, every nested route is constrained, because `Model.associated_with(entity)` can see the path from a record to its tenant by reading your associations.
+
+## How the path gets resolved
+
+In a defined order, cheapest first:
+
+1. **A custom scope** named `associated_with_<entity_name>`. Highest priority, full SQL control.
+2. **A direct `belongs_to`** to the entity class. Plain `WHERE`, most efficient.
+3. **`has_one` or `has_one :through`** to the entity class. A JOIN plus a WHERE, auto-detected by reflecting on the model's associations.
+4. **A reverse `has_many`** from the entity. Works, requires a JOIN, and logs a warning because you can almost always do better.
+
+If none apply, you get an error that names both classes:
+
+```
+Could not resolve the association between 'Invoice' and 'Organization'
+```
+
+That error is the feature. It fires at the moment the relationship is undeclared, rather than letting the read succeed unscoped and become an incident later. A framework that guessed here, or silently returned everything, would be worse than one that stops.
+
+## The wrong fix
+
+The tempting response to that error is to reach for the policy:
+
+```ruby
+# Don't.
+relation_scope do |relation|
+  skip_default_relation_scope!
+  relation.joins(:contract).where(contracts: {organization_id: entity_scope.id})
+end
+```
+
+It works. It costs three things.
+
+You needed `skip_default_relation_scope!` to get here, because an override is otherwise required to compose `default_relation_scope`, which calls the resolver that is already failing. So you switched off the framework's scoping in order to hand-write a replacement for it.
+
+`default_relation_scope` does more than tenant filtering. On a nested route it scopes children through the parent association instead. Your entity join covers one of those two branches, so nested routes lose their scoping.
+
+And it holds only where you wrote it. The next place that needs this relationship needs the join written again.
+
+## The right fix
+
+Put the resolution on the model, where the relationship actually lives:
+
+```ruby
+class Invoice < ApplicationRecord
+  belongs_to :contract
+
+  scope :associated_with_organization, ->(org) {
+    joins(:contract).where(contracts: {organization_id: org.id})
+  }
+end
+```
+
+Now `Invoice` scopes exactly the way `Project` does. The index, the show page, nested routes, the export, the typeahead and the authorization scope all behave identically, because they all go through the same resolver. You replaced one lookup, not the mechanism.
+
+And the next person who adds a read path gets the scoping for free, without knowing this conversation happened.
+
+## The general shape
+
+This is convention-over-configuration doing the thing it is supposed to do, one layer above where Rails usually does it. The convention covers the common cases. The exception gets a named, obvious place to live. And critically, the exception lives on the **model**, so it applies everywhere the record is read, instead of everywhere somebody remembered to apply it.
+
+The same instinct shows up in the sharp edges:
+
+- **Two associations to the same tenant class** and Plutonium refuses to guess which one scopes the record. You override `scoped_entity_association` on the controller. A framework that picked one for you would be picking your security model by coin flip.
+- **Debugging a scope** is `skip_default_relation_scope!`, an explicit, greppable opt-out. Not a `where` bypass that survives review because it looks like ordinary code.
+- **A portal with no `scope_to_entity`** sees everything, which is the right way to build a super-admin view: an explicit absence of scoping, in one obvious place, rather than a special case threaded through policies.
+
+## Where this stops
+
+None of this protects you from a raw `Invoice.where(...)` in a script, or from a controller you hand-wrote that never asks the policy. It scopes the paths that go through Plutonium, which is most of them in a Plutonium app, and none of them outside it.
+
+For cross-resource reads in your own code, the equivalent discipline is to use `authorized_resource_scope(OtherModel)` rather than `OtherModel.all`, because that applies the other resource's `relation_scope` and the current policy context instead of bypassing both.
+
+The rule is short enough to remember: if scoping fails, the model is missing a relationship. Say what the relationship is. Do not describe the query to the policy.