plutonium 0.50.0 → 0.52.0

data/docs/superpowers/plans/2026-05-15-public-pages-overhaul.md.tasks.json

@@ -0,0 +1,109 @@
+{
+  "planPath": "docs/superpowers/plans/2026-05-15-public-pages-overhaul.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 0: Shared CSS tokens and primitives",
+      "status": "pending",
+      "description": "**Goal:** Add design-system tokens to docs/.vitepress/theme/custom.css.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/custom.css\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"tokens defined\",\"primitives render\",\"no regressions\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 1: HomeHero component",
+      "status": "pending",
+      "blockedBy": [1],
+      "description": "**Goal:** Build the locked hero.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeHero.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"hero renders\",\"cursor blinks\",\"responsive\",\"CTAs work\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 2: HomeStopWriting (Section 1)",
+      "status": "pending",
+      "blockedBy": [1, 2],
+      "description": "**Goal:** Surface-area before/after.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeStopWriting.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"section renders\",\"stats correct\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 3: HomePillars (Section 2)",
+      "status": "pending",
+      "blockedBy": [1, 3],
+      "description": "**Goal:** Four-pillar grid.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomePillars.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"4 pillars render\",\"copy verbatim\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 4: HomeWalkthrough layout (Section 3)",
+      "status": "pending",
+      "blockedBy": [1, 4],
+      "description": "**Goal:** Walkthrough section layout with placeholders.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeWalkthrough.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"layout reserves space\",\"labels visible\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 6,
+      "subject": "Task 5: HomeAudienceSplit (Section 4)",
+      "status": "pending",
+      "blockedBy": [1, 5],
+      "description": "**Goal:** Side-by-side audience split.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeAudienceSplit.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"two columns\",\"locked copy\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 7,
+      "subject": "Task 6: HomeInTheBox (Section 5)",
+      "status": "pending",
+      "blockedBy": [1, 6],
+      "description": "**Goal:** Categorized in-the-box section.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeInTheBox.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"3 rows render\",\"copy matches spec\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 8,
+      "subject": "Task 7: HomeCta with template-toggle pills (Section 6)",
+      "status": "pending",
+      "blockedBy": [1, 7],
+      "description": "**Goal:** Manifesto CTA with reactive template-toggle pills.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeCta.vue\",\"docs/.vitepress/theme/index.ts\",\"docs/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"pills toggle\",\"URLs correct\",\"CTAs link\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 9,
+      "subject": "Task 8: SectionLanding shared component",
+      "status": "pending",
+      "blockedBy": [1],
+      "description": "**Goal:** Reusable rail+sidebar layout for section landings.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/SectionLanding.vue\",\"docs/.vitepress/theme/index.ts\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"numbered renders\",\"categorized renders\",\"responsive\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 10,
+      "subject": "Task 9: Getting Started landing",
+      "status": "pending",
+      "blockedBy": [9],
+      "description": "**Goal:** Rewrite getting-started/index.md.\n\n```json:metadata\n{\"files\":[\"docs/getting-started/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"8 steps render\",\"links resolve\",\"prereqs preserved\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 11,
+      "subject": "Task 10: Guides landing",
+      "status": "pending",
+      "blockedBy": [9],
+      "description": "**Goal:** Rewrite guides/index.md.\n\n```json:metadata\n{\"files\":[\"docs/guides/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"categories render\",\"links resolve\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 12,
+      "subject": "Task 11: Reference landing",
+      "status": "pending",
+      "blockedBy": [9],
+      "description": "**Goal:** Rewrite reference/index.md.\n\n```json:metadata\n{\"files\":[\"docs/reference/index.md\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"categories match real sidebar\",\"links resolve\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 13,
+      "subject": "Task 12: Demo app + asciinema + screenshots",
+      "status": "pending",
+      "description": "**Goal:** Produce walkthrough assets from a fresh demo app.\n\n```json:metadata\n{\"files\":[\"docs/public/images/home-portal.png\",\"docs/public/images/home-index.png\",\"docs/public/images/home-form.png\",\"docs/public/asciinema/home-scaffold.cast\"],\"verifyCommand\":\"ls -la docs/public/images/home-*.png docs/public/asciinema/home-scaffold.cast\",\"acceptanceCriteria\":[\"4 assets exist\",\"non-empty\",\"correct format\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 14,
+      "subject": "Task 13: Wire assets into HomeWalkthrough",
+      "status": "pending",
+      "blockedBy": [5, 13],
+      "description": "**Goal:** Replace placeholders with real screenshots + asciinema embed.\n\n```json:metadata\n{\"files\":[\"docs/.vitepress/theme/components/HomeWalkthrough.vue\",\"docs/.vitepress/theme/index.ts\"],\"verifyCommand\":\"yarn docs:dev\",\"acceptanceCriteria\":[\"screenshots render\",\"asciinema plays\",\"no console errors\"],\"requiresUserVerification\":false}\n```"
+    },
+    {
+      "id": 15,
+      "subject": "Task 14: Visual sweep + user verification",
+      "status": "pending",
+      "blockedBy": [8, 10, 11, 12, 14],
+      "description": "**Goal:** Cross-cutting sweep and user sign-off.\n\n```json:metadata\n{\"files\":[],\"verifyCommand\":\"yarn docs:build\",\"acceptanceCriteria\":[\"all 4 pages render in both modes\",\"no console errors\",\"build succeeds\",\"user approved\"],\"requiresUserVerification\":true,\"userVerificationPrompt\":\"All four public pages are live in `yarn docs:dev`. Have you reviewed Home, Getting Started, Guides, and Reference and are they ready to ship?\"}\n```"
+    }
+  ],
+  "lastUpdated": "2026-05-15T00:00:00Z"
+}

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?

data/docs/superpowers/specs/2026-05-13-docs-restructure-design.md

@@ -0,0 +1,186 @@
+# Docs Restructure & Compaction Design
+
+**Date:** 2026-05-13
+**Status:** Draft — awaiting approval
+
+## Problem
+
+Following the skill consolidation (19 → 8 skills, ~37% volume cut), the `docs/` site is misaligned in two ways:
+
+1. **Reference structure** mirrors the OLD skill structure (separate `model/`, `definition/`, `policy/`, `controller/`, `interaction/`, `views/`, `assets/`, `portal/`, `generators/`). It should mirror the new 7 functional areas.
+2. **Concept/task split is muddled.** Some "guides" are really concept explanations (e.g. `guides/authorization.md` overlaps `reference/policy/`). Some concepts have NO reference home (auth, tenancy, testing — they live in `guides/` only).
+
+## Goals
+
+**Primary goal: quality.** Volume reduction is incidental.
+
+1. Restructure `reference/` to mirror the 7 functional areas from the skill consolidation — so readers can predict where to look.
+2. Establish a clean role split: **guides = task recipes ("how do I X")**, **reference = concept lookup ("what does X do")**. Some duplication is fine when framed as different entry points; tables of options live in ONE place.
+3. Improve every page on these axes:
+   - **Right place** — concepts in reference, recipes in guides.
+   - **Right structure** — 🚨 callouts at top for "you'll regret this" rules; option/decision tables for scannability; decision rules over generic exhortations.
+   - **Right content** — keep WHY explanations that help reason about edge cases; cut marketing copy and empty "best practices" exhortations; verify technical accuracy as we go (the skill work caught real bugs — same energy).
+4. Light pass on the tutorial — preserve narrative flow; improve clarity where prose is unclear.
+
+## Non-Goals
+
+- Restructuring `getting-started/` navigation (the tutorial arc stays).
+- Changing VitePress theme, search provider, or build pipeline.
+- Adding new content beyond reorganizing what exists.
+
+## Current state
+
+40 markdown files, ~13,222 lines.
+
+| Area | Files | Notes |
+|---|---|---|
+| `getting-started/` | 11 | Index + installation + 8-step tutorial. Narrative learning arc. |
+| `guides/` | 14 | Task-oriented but inconsistent — some concept-heavy. |
+| `reference/` | 16 | Concept-by-concept, mirrors the OLD skill structure. |
+
+## Target reference structure (mirrors 7 skill areas)
+
+```
+reference/
+├── index.md          ← rewritten overview, links to the 7 areas
+├── app/
+│   ├── index.md      ← installation, configuration
+│   ├── packages.md   ← feature + portal packages
+│   ├── portals.md    ← portal engines, mounting, route registration
+│   └── generators.md ← full generator catalog
+├── resource/
+│   ├── index.md      ← overview, the 4 layers
+│   ├── model.md      ← `Plutonium::Resource::Record`, has_cents, SGID, routing (merges current model/)
+│   ├── definition.md ← field/input/display/column, page chrome (merges current definition/index + fields)
+│   ├── query.md      ← search, filters, scopes, sort
+│   └── actions.md    ← custom + bulk actions
+├── behavior/
+│   ├── index.md      ← overview, the controller/policy/interaction trio
+│   ├── controllers.md ← hooks, key methods, presentation
+│   ├── policies.md   ← actions, permitted attributes, associations, relation_scope
+│   └── interactions.md ← structure, outcomes, chaining, URL generation
+├── ui/
+│   ├── index.md      ← overview
+│   ├── pages.md      ← IndexPage/ShowPage/NewPage/EditPage, hooks
+│   ├── forms.md      ← field builder, layouts, theming, association inputs (current views/forms.md)
+│   ├── displays.md   ← Display class, custom rendering
+│   ├── tables.md     ← Table class, customization
+│   ├── components.md ← component kit, custom Phlex components
+│   ├── layouts.md    ← shell, eject, ResourceLayout
+│   └── assets.md     ← Tailwind config, Stimulus, design tokens, .pu-* classes (current assets/)
+├── auth/             ← NEW (currently only in guides/)
+│   ├── index.md      ← Rodauth overview
+│   ├── accounts.md   ← basic, admin, SaaS account types
+│   └── profile.md    ← profile resource, SecuritySection
+├── tenancy/          ← NEW (currently spread across guides/)
+│   ├── index.md      ← overview, three pieces (portal/policy/model)
+│   ├── entity-scoping.md ← associated_with, three model shapes
+│   ├── nested-resources.md ← parent/child routes, scoping
+│   └── invites.md    ← invitation system
+└── testing/          ← NEW (currently only in guides/)
+    ├── index.md
+    ├── crud.md
+    ├── policy.md
+    ├── nested.md
+    ├── portal-access.md
+    └── auth-helpers.md
+```
+
+### Content migrations
+
+| Current file | Goes to |
+|---|---|
+| `reference/model/index.md` + `features.md` | `reference/resource/model.md` |
+| `reference/definition/index.md` + `fields.md` | `reference/resource/definition.md` |
+| `reference/definition/query.md` | `reference/resource/query.md` |
+| `reference/definition/actions.md` | `reference/resource/actions.md` |
+| `reference/controller/index.md` | `reference/behavior/controllers.md` |
+| `reference/policy/index.md` | `reference/behavior/policies.md` |
+| `reference/interaction/index.md` | `reference/behavior/interactions.md` |
+| `reference/views/index.md` | split → `pages.md`, `displays.md`, `tables.md`, `components.md`, `layouts.md` |
+| `reference/views/forms.md` | `reference/ui/forms.md` |
+| `reference/assets/index.md` | `reference/ui/assets.md` |
+| `reference/portal/index.md` | `reference/app/portals.md` |
+| `reference/generators/index.md` | `reference/app/generators.md` |
+| `getting-started/installation.md` | concept part → `reference/app/index.md`; task part stays |
+| `guides/authentication.md` | concept part → `reference/auth/index.md` + `accounts.md`; recipe stays |
+| `guides/user-profile.md` | concept part → `reference/auth/profile.md`; recipe stays |
+| `guides/multi-tenancy.md` | concept part → `reference/tenancy/entity-scoping.md`; recipe stays |
+| `guides/nested-resources.md` | concept part → `reference/tenancy/nested-resources.md`; recipe stays |
+| `guides/user-invites.md` | concept part → `reference/tenancy/invites.md`; recipe stays |
+| `guides/testing.md` | concept part → `reference/testing/*`; recipe stays |
+| `guides/creating-packages.md` | concept part → `reference/app/packages.md`; recipe stays |
+
+## Guides restructure
+
+Each guide becomes a clean **task recipe**:
+
+- Single goal stated at the top ("Add authentication to your app")
+- Numbered step-by-step
+- Each step links to the relevant reference page for "why" and "what else"
+- No exhaustive option tables (those live in reference)
+- ~50-150 lines each, down from ~300-600
+
+Keep the 14 guides at their current paths so external links don't break.
+
+## Editing principles (quality-first)
+
+Not "cut everything"; cut what doesn't earn its keep. Specifically:
+
+**Cut:**
+- Marketing copy ("Plutonium is awesome because…").
+- Empty "best practices" exhortations ("write clean code", "test your code").
+- Content duplicated across pages — one canonical home + cross-link.
+- Verbose prose where a 10-line snippet shows the same thing.
+- Rails-101 explanations that don't set up a Plutonium twist.
+
+**Keep — and add more of:**
+- **WHY explanations** that help readers reason about edge cases.
+- **Non-obvious gotchas** — the dangerous-default stuff that bites people.
+- **Decision rules** ("use X when you need Y") over generic exhortations.
+- **Option / field / DSL tables** — readers scan them, they don't read prose.
+- **Inline code examples** that work — copy-pasteable, no `...` stand-ins.
+- **🚨 callouts at top of each page** for the "you'll regret this" rules.
+
+**Verify as we go.** The skill work caught real bugs (auto-detection rules, association input behavior, action visibility flags, `views` DSL naming). Same energy here — when prose claims X, check the source.
+
+## Tutorial compaction pass
+
+Same cuts as above, but preserve:
+
+- Step structure (1-8 stays)
+- Narrative flow (one step builds on the next)
+- Frequent "expected output" / "verify" callouts
+- Screenshots and visuals (keep all references)
+
+Target: 10-20% volume reduction without losing pedagogical value.
+
+## VitePress sidebar rewrite
+
+`.vitepress/config.ts` sidebar rewritten for the new structure. Three sidebars:
+
+- `/getting-started/` — unchanged
+- `/guides/` — same 14 entries, reorganized into the 7 functional groups
+- `/reference/` — new 7-area structure
+
+## Rollout
+
+1. **Pilot one reference area** — pick `reference/resource/` (largest, most-read). Build it from scratch using the merged skills as the template. Get user feedback on shape.
+2. **Build out the other 6 areas** — one at a time or in parallel, your call.
+3. **Move concept content** from guides into reference. Hollow guides become recipes.
+4. **Tutorial compaction pass** — minimal, last.
+5. **Rewrite VitePress sidebar** — once all paths exist.
+6. **Delete old reference directories** — `model/`, `definition/`, `policy/`, etc. — in one sweep after everything's in place.
+7. **Build the site locally** — verify no dead links, search index regenerates cleanly.
+
+## Risks
+
+- **External links break.** GitHub PRs, blog posts, Stack Overflow answers may link to `reference/model/`, `reference/definition/actions`, etc. Mitigation: VitePress supports redirects, OR keep stub pages that redirect via meta refresh. Cheap to add.
+- **Guides ↔ reference duplication drifts.** If a recipe and its reference page describe the same option differently, readers get confused. Mitigation: linting (no duplicate DSL/option tables across guide + reference).
+- **Volume isn't the metric.** Some pages will get longer (currently underdeveloped topics: tenancy, testing, profile). Some will get shorter. The win is navigability and clarity, not line count.
+
+## Open questions
+
+- Add `.vitepress` redirect configuration for old reference paths? (Recommended: yes, low cost.)
+- Should `reference/app/generators.md` be the full catalog or a per-area split? (Recommended: full catalog — it's reference, scannability matters.)
+- Are there guides that should be **deleted entirely** because they're 100% concept overlap with reference? (Decide after pilot.)