plutonium 0.50.0 → 0.51.0

data/docs/reference/ui/pages.md

@@ -0,0 +1,189 @@
+# Pages
+
+Each definition has nested page classes for index / show / new / edit / interactive-action. Override the ones you need.
+
+## Architecture
+
+```
+Definition
+├── IndexPage              → renders Table
+├── ShowPage               → renders Display
+├── NewPage                → renders Form
+├── EditPage               → renders Form
+└── InteractiveActionPage  → renders Form
+```
+
+## Page classes
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class IndexPage              < IndexPage; end
+  class ShowPage               < ShowPage; end
+  class NewPage                < NewPage; end
+  class EditPage               < EditPage; end
+  class InteractiveActionPage  < InteractiveActionPage; end
+  class Form                   < Form; end
+  class Table                  < Table; end
+  class Display                < Display; end
+end
+```
+
+## Page titles, descriptions, breadcrumbs
+
+```ruby
+class PostDefinition < ResourceDefinition
+  index_page_title       "Blog Posts"
+  index_page_description "Manage all published articles"
+  show_page_title        "Article Details"
+  show_page_title        -> { current_record!.title }   # dynamic
+  new_page_title         "Create Post"
+  edit_page_title        -> { "Edit: #{current_record!.title}" }
+
+  breadcrumbs              true     # global default
+  index_page_breadcrumbs   false    # per-page override
+  show_page_breadcrumbs    true
+  new_page_breadcrumbs     true
+  edit_page_breadcrumbs    true
+  interactive_action_page_breadcrumbs true
+end
+```
+
+## Page hooks (preferred over `view_template`)
+
+Every page inherits these — use them instead of overriding `view_template` to preserve breadcrumbs, header, and DynaFrame behavior:
+
+| Hook | Position |
+|---|---|
+| `render_before_header` / `_after_header` | wraps the entire header section |
+| `render_before_breadcrumbs` / `_after_breadcrumbs` | around the breadcrumb row |
+| `render_before_page_header` / `_after_page_header` | around the title + actions block |
+| `render_before_toolbar` / `_after_toolbar` | around the action toolbar |
+| `render_before_content` / `_after_content` | around main content |
+| `render_before_footer` / `_after_footer` | around footer/pagination |
+
+Example:
+
+```ruby
+class ShowPage < ShowPage
+  private
+
+  def page_title
+    "#{object.title} — #{object.author.name}"
+  end
+
+  def render_before_content
+    div(class: "alert alert-info") do
+      plain "This post has #{object.comments.count} comments"
+    end
+  end
+
+  def render_after_content
+    render RelatedPostsComponent.new(post: object)
+  end
+
+  def render_toolbar
+    div(class: "flex gap-2") do
+      button(class: "pu-btn pu-btn-md pu-btn-secondary") { "Preview" }
+      button(class: "pu-btn pu-btn-md pu-btn-primary")   { "Publish" }
+    end
+  end
+end
+```
+
+## Custom ERB views (full replacement)
+
+For total control, drop the page class entirely with an ERB view at the controller path:
+
+```
+app/views/posts/show.html.erb
+packages/admin_portal/app/views/admin_portal/posts/show.html.erb
+```
+
+The default view simply renders the page class:
+
+```erb
+<%= render current_definition.show_page_class.new %>
+```
+
+Mix — keep the default and add chrome around it:
+
+```erb
+<div class="announcement-banner">Special announcement</div>
+<%= render current_definition.show_page_class.new %>
+<div class="related"><%= render partial: "related" %></div>
+```
+
+## Detecting render context
+
+| Helper | True when |
+|---|---|
+| `in_frame?` | Request targets a turbo-frame |
+| `in_modal?` | Request renders inside a modal/slideover (primary or secondary) |
+| `in_secondary_modal?` | Request renders inside the stacked secondary modal |
+
+Use to pin action strips, omit nav chrome, or swap layouts.
+
+### Stacked modals (secondary frame)
+
+Association inputs include an inline `+` button. When the parent form is itself rendered in a modal, the `+` opens a **second stacked modal** in `Plutonium::REMOTE_MODAL_SECONDARY_FRAME` instead of replacing the primary modal. On successful create, the secondary closes and the primary frame reloads so the new record appears in the select — no developer wiring.
+
+For custom flows: `helpers.turbo_stream_close_frame(frame_id)` and `helpers.turbo_stream_reload_frame(frame_id)` are available.
+
+See [Forms › Association inputs](./forms#association-inputs).
+
+## Modals & slideovers
+
+The framework's `:new` / `:edit` actions render inline inside a modal. Choose the chrome per-resource via the definition:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  modal :slideover    # default — slide-in panel from the right
+  # modal :centered   # centered dialog
+  # modal false       # full standalone pages (no modal)
+end
+```
+
+Custom interactive actions render in their own dialog with their own per-action `modal:` option (`:centered` default, or `:slideover`). See [Resource › Actions](/reference/resource/actions#action-options).
+
+## Tabs on the show page
+
+Show pages with `permitted_associations` (see [Behavior › Policy](/reference/behavior/policies#association-permissions)) render a tablist: **Details** tab first, then one tab per association. The active tab is reflected in the URL hash (`#products`, `#refund-requests`) so the page deep-links and the active state survives reload / back navigation. Tab rows scroll horizontally on narrow viewports — they don't wrap.
+
+## Portal-specific overrides
+
+Each portal can override page classes independently. The portal definition inherits from the base definition, and its nested classes inherit from the base's nested classes:
+
+```ruby
+class AdminPortal::PostDefinition < ::PostDefinition
+  class ShowPage < ShowPage     # inherits from ::PostDefinition::ShowPage
+    def render_after_content
+      super
+      render AdminOnlySection.new(post: object)
+    end
+  end
+end
+```
+
+## Available context
+
+Inside any page / form / display / Phlex component, the same set of helpers is available — model accessors, definition/policy methods, URL helpers, `current_user`. For the full list, see [Behavior › Controllers › Key methods](/reference/behavior/controllers#key-methods) — pages inherit the same surface.
+
+In Phlex components, Rails helpers are accessed via the `helpers` proxy:
+
+```ruby
+class MyComponent < Plutonium::UI::Component::Base
+  def view_template
+    helpers.link_to(...)
+    helpers.number_to_currency(...)
+  end
+end
+```
+
+## Related
+
+- [Forms](./forms) — Form class, field builder, themes
+- [Displays](./displays) — show-page Display class
+- [Tables](./tables) — index-page Table class
+- [Components](./components) — built-in component kit, custom Phlex components, DynaFrame
+- [Layouts](./layouts) — overall shell, eject, ResourceLayout
+- [Resource › Definition](/reference/resource/definition) — page titles, breadcrumbs, modal mode, metadata panel

data/docs/reference/ui/tables.md

@@ -0,0 +1,117 @@
+# Tables
+
+The index page's table rendering. Override the `Table` nested class in your definition for custom layouts (e.g. card grids).
+
+## Custom table template
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Table < Table
+    def view_template
+      render_search_bar
+      render_scopes_bar
+
+      if collection.empty?
+        render_empty_card
+      else
+        # Replace the table with a card grid
+        div(class: "grid grid-cols-3 gap-4") do
+          collection.each { |post| render PostCardComponent.new(post:) }
+        end
+      end
+
+      render_footer
+    end
+  end
+end
+```
+
+## Methods
+
+| Method | Purpose |
+|---|---|
+| `render_search_bar` | Toolbar search input |
+| `render_scopes_bar` | Quick-filter scope buttons |
+| `render_table` | Default table rendering |
+| `render_empty_card` | Empty state |
+| `render_footer` | Pagination |
+| `collection` | Paginated records |
+| `resource_fields` | Column field names |
+
+## Per-column customization
+
+Prefer declaring column behavior in the **definition** rather than overriding the entire `Table`:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  column :title,  align: :start    # default
+  column :status, align: :center
+  column :amount, align: :end
+
+  # formatter — receives just the value
+  column :description, formatter: ->(value) { value&.truncate(30) }
+  column :price,       formatter: ->(value) { "$%.2f" % value if value }
+
+  # block — receives the full record
+  column :full_name do |record|
+    "#{record.first_name} #{record.last_name}"
+  end
+end
+```
+
+See [Resource › Definition › Column options](/reference/resource/definition#column-options).
+
+## Grid view
+
+For card-based layouts as a switchable alternative to the table, use the built-in Grid view — declare `grid_fields` in the definition:
+
+```ruby
+class UserDefinition < ResourceDefinition
+  grid_fields(
+    image:     :avatar,
+    header:    :name,
+    subheader: :email,
+    body:      :bio,
+    meta:      [:role, :status],
+    footer:    :last_seen_at
+  )
+
+  default_index_view :grid
+end
+```
+
+See [Resource › Definition › Index views](/reference/resource/definition#index-views-table-grid). You only need a custom `Table` class when you want something neither Table nor Grid covers.
+
+## Theming
+
+Override the theme via a nested `Theme` class:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Table < Table
+    class Theme < Plutonium::UI::Table::Theme
+      def self.theme
+        super.merge(
+          wrapper:     "pu-table-wrapper",
+          base:        "pu-table",
+          header:      "pu-table-header",
+          header_cell: "pu-table-header-cell",
+          body_row:    "pu-table-body-row",
+          body_cell:   "pu-table-body-cell"
+        )
+      end
+    end
+  end
+end
+```
+
+### Theme keys
+
+`wrapper`, `base`, `header`, `header_cell`, `body_row`, `body_cell`, `sort_icon`.
+
+## Related
+
+- [Pages](./pages) — `IndexPage` render hooks (a lighter alternative for top/bottom chrome)
+- [Components](./components) — `PostCardComponent` and other reusable Phlex pieces
+- [Resource › Definition](/reference/resource/definition) — column configuration, grid view
+- [Resource › Query](/reference/resource/query) — search, filters, scopes, sort

data/docs/superpowers/specs/2026-05-09-typeahead-endpoint-design.md

@@ -0,0 +1,203 @@
+# Typeahead Endpoint Design
+
+**Status:** Approved (2026-05-09)
+**Author:** stefan
+**Scope:** New backend-driven typeahead/autocomplete primitive for resource form inputs and index filter inputs.
+
+## Goal
+
+Add an async typeahead endpoint to every Plutonium resource so association-backed selects (and any future typeahead-capable input) can fetch matching records from the server instead of materialising up to `DEFAULT_CHOICE_LIMIT` options into the page at render time. This unblocks association pickers over large tables (where the existing 100-row cap silently truncates) without forcing every input into a custom JS solution.
+
+## Non-goals
+
+- Pagination of typeahead results (we use a hard cap with an overflow indicator; pagination can be added later if a real need surfaces).
+- Rich result rows (subtitle, icon, avatar). MVP returns minimal `{value, label}` per row; richer payloads are a separate iteration.
+- Replacing the existing eager-list ResourceSelect; the eager path stays as the fallback / small-table mode.
+
+## Architecture
+
+Three layers, mirroring how `Plutonium::Resource::Controllers::InteractiveActions` is composed today.
+
+### 1. Routing — `Plutonium::Routing::MapperExtensions`
+
+Two routes are added to the existing `interactive_resource_actions` concern (auto-mounted on every Plutonium resource alongside `record_actions`, `bulk_actions`, etc.):
+
+```
+GET /<resource>/typeahead/input/:name?q=…   → typeahead_input
+GET /<resource>/typeahead/filter/:name?q=…  → typeahead_filter
+```
+
+Both collection-level. **No member variant** — authorization on the parent resource class is sufficient (see "Authorization" below).
+
+### 2. Controller concern — `Plutonium::Resource::Controllers::Typeahead`
+
+Two thin actions plus a single `before_action` for auth.
+
+```ruby
+module Plutonium::Resource::Controllers::Typeahead
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :authorize_typeahead!, only: %i[typeahead_input typeahead_filter]
+  end
+
+  def typeahead_input
+    name = params[:name].to_sym
+    defn = current_definition.defined_inputs[name]
+    return head(:not_found) unless defn
+
+    render_typeahead_response(defn)
+  end
+
+  def typeahead_filter
+    name = params[:name].to_sym
+    filter = current_query_object.filter_definitions[name]
+    return head(:not_found) unless filter
+
+    defn = filter.defined_inputs[:value]
+    return head(:not_found) unless defn
+
+    render_typeahead_response(defn)
+  end
+
+  private
+
+  def render_typeahead_response(defn)
+    klass = lookup_input_class(defn)
+    return render(json: { error: "input is not typeahead-capable" }, status: :bad_request) unless klass < Plutonium::UI::Form::Components::Searchable
+
+    widget = klass.build_for_typeahead(defn[:options] || {})
+    results, has_more = widget.typeahead(
+      query: params[:q].to_s,
+      limit: TYPEAHEAD_LIMIT,
+      controller: self
+    )
+    render json: { results: results, has_more: has_more }
+  end
+
+  def authorize_typeahead!
+    authorize! resource_class, to: :typeahead?
+  end
+
+  # Maps the input definition's :as symbol (e.g. :resource_select) to a
+  # component class. Backed by an explicit registry — only inputs that
+  # opted in by including Searchable register here, so anything not in
+  # the registry falls through to the 400 branch.
+  def lookup_input_class(defn)
+    Plutonium::UI::Form::Components::Searchable.registry[defn[:options]&.[](:as)&.to_sym]
+  end
+end
+```
+
+`TYPEAHEAD_LIMIT` is a module-level constant (default `50`). Easy to tune.
+
+### 3. Search behavior — `Plutonium::UI::Form::Components::Searchable`
+
+A small mixin. Mixed into `ResourceSelect` (and into any future input that wants typeahead). Two-method public surface:
+
+```ruby
+module Plutonium::UI::Form::Components::Searchable
+  extend ActiveSupport::Concern
+
+  # Maps :as symbol -> component class. Each typeahead-capable widget
+  # populates this when it includes Searchable so the controller can
+  # dispatch by name without a brittle inflection convention.
+  def self.registry
+    @registry ||= {}
+  end
+
+  class_methods do
+    # Subclasses call this to claim their :as symbol in the registry.
+    def typeahead_input_name(name)
+      Plutonium::UI::Form::Components::Searchable.registry[name.to_sym] = self
+    end
+
+    # Allocates the widget and assigns just the ivars #typeahead needs.
+    # Bypasses Phlex's render-time build_attributes pipeline so we don't
+    # need a field/form context to run the search.
+    def build_for_typeahead(options)
+      allocate.tap { |w| w.send(:apply_typeahead_options, options) }
+    end
+  end
+
+  # Returns [results_array, has_more_bool]. results entries are { value:, label: }.
+  def typeahead(query:, limit:, controller:)
+    raw = collect_typeahead_candidates(query, controller: controller)
+    over = raw.length > limit
+    [raw.first(limit).map { |r| serialize_typeahead_row(r) }, over]
+  end
+end
+```
+
+`ResourceSelect` implements `apply_typeahead_options`, `collect_typeahead_candidates`, and `serialize_typeahead_row`:
+
+- `apply_typeahead_options(options)` reads `@association_class`, `@raw_choices`, `@choice_limit`, `@skip_authorization` from the input definition's options hash — the same keys the existing `build_attributes` consumes at render time.
+- `collect_typeahead_candidates` branches:
+  - if `@raw_choices` (static list) — `@raw_choices.select { |label, _| label.to_s.downcase.include?(query.downcase) }`. No auth: choices are static, definition-author-controlled.
+  - elsif `@association_class` — runs the search through `controller.send(:authorized_resource_scope, @association_class)` so the associated resource's `policy.relation_scope` enforces row-level auth, then applies the associated resource definition's `search` block if present, else `LIKE` on the column backing `to_label` (or skips filtering when query is blank).
+- `serialize_typeahead_row(row)` returns `{ value: row.to_signed_global_id.to_s, label: row.to_label }` for records, or `{ value: raw_value, label: raw_label }` for static choices.
+
+The cap is **`limit + 1`** at the SQL level (`LIMIT 51` for a `limit: 50` request) so we can detect overflow without a separate `COUNT`.
+
+## Authorization
+
+Two gates, layered:
+
+1. **Parent gate** — `policy.typeahead?` on the resource hosting the endpoint. Defaults to `index?` (collection-shaped — typeahead is "list/search records of this class", not "show one record"). Override per-resource if needed (e.g. `def typeahead? = create? || update?` to require write intent).
+2. **Row gate** — when the input is association-backed, results are scoped through the *associated* resource's `policy.relation_scope` via the existing `authorized_resource_scope` helper. So a user can typeahead Authors only if they're allowed to read Authors, regardless of whether they can edit Posts.
+
+Static `choices` lists bypass the row gate (they're not records, they're definition-author-controlled enumerations).
+
+## Data flow
+
+```
+Browser (Stimulus controller)
+  fetch GET /widgets/typeahead/input/author?q=ali
+    ↓
+Typeahead#typeahead_input
+  authorize_typeahead! → policy.typeahead? on Widget       [parent gate]
+  defn = current_definition.defined_inputs[:author]
+  widget = ResourceSelect.build_for_typeahead(defn[:options])
+  widget.typeahead(query: "ali", limit: 50, controller: self)
+    authorized_resource_scope(User).where("name LIKE ?", "%ali%").limit(51)   [row gate]
+    serialize each → { value: sgid, label: to_label }
+  render json: { results: [...], has_more: false }
+```
+
+## Components
+
+| File | Responsibility |
+|---|---|
+| `lib/plutonium/routing/mapper_extensions.rb` | Add 2 routes to the `interactive_resource_actions` concern. |
+| `lib/plutonium/resource/controllers/typeahead.rb` | **New.** Controller concern with `typeahead_input`/`typeahead_filter` actions, auth, dispatch, JSON serialization. |
+| `lib/plutonium/resource/controller.rb` | Include `Controllers::Typeahead`. |
+| `lib/plutonium/resource/policy.rb` | Add `typeahead?` defaulting to `index?`. |
+| `lib/plutonium/ui/form/components/searchable.rb` | **New.** `Searchable` mixin (class-level `build_for_typeahead`, instance-level `typeahead`). |
+| `lib/plutonium/ui/form/components/resource_select.rb` | Include `Searchable`, call `typeahead_input_name :resource_select` to register. Implement `apply_typeahead_options`, `collect_typeahead_candidates`, `serialize_typeahead_row`. Wire Stimulus controller + remote URL data attrs into the rendered `<select>`. |
+| `src/js/controllers/resource_select_controller.js` | **New.** Stimulus controller: debounced fetch, populates options on the underlying `<select>`, surfaces overflow hint, handles network errors. |
+
+## Error handling
+
+- Unknown input/filter name → `404 Not Found`.
+- Input class registered but doesn't include `Searchable` → `400 Bad Request` with `{error: "input is not typeahead-capable"}`.
+- Authorization failure → existing `ActionPolicy::Unauthorized` flow → `403`.
+- Empty/blank `q` → return all candidates within the cap (so initial dropdown open shows something useful, mirroring the eager mode).
+- Network/parse errors on the JS side → controller leaves the existing `<select>` options intact and shows a small "couldn't search" inline notice; user can retry.
+
+## Testing
+
+- **Unit — `Searchable#typeahead` (ResourceSelect):** static choices filter case-insensitively; association case routes through `authorized_resource_scope`; overflow detection (`limit+1` rows in DB → `has_more: true`); blank query returns top-N.
+- **Controller — `Typeahead#typeahead_input` / `typeahead_filter`:** happy path renders correct JSON envelope; unknown name → 404; non-searchable input class → 400; auth denied → 403.
+- **Integration:** full request through `admin_portal` hitting a registered resource, verifying SGID round-trip (the value in the response is accepted by ResourceSelect on form submit).
+- **JS — Stimulus controller:** debounces input, handles `has_more`, handles network errors. Lightweight, behavior-focused.
+
+## Migration & rollout
+
+- Existing eager `ResourceSelect` keeps working — typeahead is opt-in per render via a flag on the input definition (e.g. `as: :resource_select, typeahead: true`). When unset, the component renders today's eager list. The Stimulus controller only attaches when `data-resource-select-typeahead-url-value` is present.
+- Filter inputs default to typeahead when the underlying input class supports it (filters are the worst pain point for the 100-row cap).
+
+## Open questions / deferred
+
+- Server-driven sort order beyond what `relation_scope` returns (e.g. recency, fuzzy-rank). Out of scope for MVP.
+- Multi-select typeahead UX (chips, paste-multiple). MVP supports `multiple: true` mechanically (the array of SGIDs round-trips fine), but the dropdown UX is single-select-shaped. Iteration.
+- Caching/coalescing repeated queries client-side. Defer.

data/docs/superpowers/specs/2026-05-12-skill-compaction-design.md

@@ -0,0 +1,99 @@
+# Skill Compaction & Consolidation Design
+
+**Date:** 2026-05-12
+**Status:** Approved (pending implementation)
+
+## Problem
+
+The `.claude/skills/` directory currently holds 19 Plutonium skills totaling ~7,846 lines. Several issues:
+
+- Skills are too verbose for a stable-API framework. Plutonium rarely changes shape, so re-explaining concepts has little ROI.
+- Several skills are read together for any non-trivial task (e.g. create-resource + model + definition). Loading them separately wastes context.
+- Some skills duplicate content (Rails-isms, philosophy preambles, repeated DSL explanations).
+
+Skills are written for **developers using the framework**, not for first-time Rails users. They should read like reference + decision rules, not tutorials.
+
+## Goals
+
+1. Reduce total skill volume by ~45% (target: ~4,150 lines from 7,846).
+2. Merge skills that are almost always loaded together.
+3. Keep skills self-contained with inline code examples (chosen over linking to `test/dummy`).
+4. Preserve high-value reference material (option/DSL/field tables).
+
+## Non-Goals
+
+- Restructuring user-facing `docs/` site.
+- Changing the framework API.
+- Splitting examples into separate files outside the skill.
+
+## Target Skill Map
+
+From 19 skills to 8:
+
+| New skill | Merges | Est. lines |
+|---|---|---|
+| `plutonium` | (router, kept) | ~150 |
+| `plutonium-app` | installation + portal + package | ~600 |
+| `plutonium-resource` | create-resource + model + definition | ~800 |
+| `plutonium-behavior` | controller + policy + interaction | ~700 |
+| `plutonium-ui` | views + forms + assets | ~700 |
+| `plutonium-auth` | (kept, compacted) | ~350 |
+| `plutonium-tenancy` | entity-scoping + nested-resources + invites | ~600 |
+| `plutonium-testing` | (kept, compacted) | ~250 |
+
+**Total: ~4,150 lines.**
+
+### Rationale per merge
+
+- **plutonium-app** — installation, portal creation, and package creation are the setup arc. Always done together on a new app.
+- **plutonium-resource** — model declarations, scaffold options, and definition DSL are the core "build a resource" workflow.
+- **plutonium-behavior** — controllers, policies, and interactions form the request/authorization/business-logic layer.
+- **plutonium-ui** — views, forms, and assets all touch presentation. Assets covers the toolchain backing both views and forms.
+- **plutonium-tenancy** — entity-scoping is the core mechanic; nested-resources and invites are both consumers of that mechanic.
+- **plutonium-auth** stays solo at the user's request (rodauth/profile is distinct enough from tenancy/invites).
+- **plutonium-testing** stays solo (orthogonal concern, loaded only for test work).
+
+## Compaction Rules
+
+Applied to every skill during merge.
+
+**Cut:**
+- Rails/Ruby basics — assume reader knows Rails.
+- Philosophy/motivation preambles.
+- Duplicated content across merged skills (one canonical location per concept).
+- Verbose prose where a 10-line snippet shows the same thing.
+- Marketing copy ("Plutonium gives you...").
+
+**Keep:**
+- Decision rules ("use X when…, Y when…").
+- Non-obvious gotchas and constraints.
+- Short canonical inline snippets.
+- **Option/field/DSL tables** — high-value reference, kept verbatim.
+- Cross-references to other skills via `[[plutonium-resource]]` style links.
+
+## Format per merged skill
+
+1. **Header paragraph** — what this covers + when to load.
+2. **Sub-sections per merged topic** — each with: decision rules → minimal inline example → gotchas → tables (where applicable).
+3. **Cross-references** at bottom.
+
+## Rollout
+
+1. **Pilot:** `plutonium-resource` first (largest, hardest — biggest signal on whether the template works).
+2. **Review pilot together** — adjust template if needed.
+3. **Apply pattern** to the remaining merges. One PR per merged skill OR all-in-one (TBD with user).
+4. **Update `plutonium` router skill** last — it references the new names.
+5. **Delete old skill directories** only after the new one lands.
+
+Skills require a gem release to take effect for users (per `CLAUDE.md`), so this ships as a single release regardless of how PRs are split.
+
+## Risks
+
+- **Loss of granularity for context loading** — a single merged skill loads more tokens even when only one sub-topic is needed. Mitigated by aggressive compaction (loose budget but still much smaller than today's biggest individual skills).
+- **Cross-references breaking** — the `plutonium` router skill and any external references must update at the same time as the merge.
+- **Drift from `docs/`** — the user-facing docs site may still reference old skill structure; out of scope for this spec but worth noting.
+
+## Open Questions
+
+- Should the merge land as one PR or eight? (Deferred to rollout time.)
+- Are there external references to the old skill names (other repos, marketplace listings) that need updating?