plutonium 0.54.0 → 0.56.0

data/docs/superpowers/plans/2026-06-04-sqlite-tune-maintenance-generators.md.tasks.json

@@ -0,0 +1,45 @@
+{
+  "planPath": "docs/superpowers/plans/2026-06-04-sqlite-tune-maintenance-generators.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 1: Extract ConfiguresRecurring concern + refactor rails_pulse",
+      "status": "completed",
+      "description": "Move env-aware recurring.yml injection into a reusable, unit-testable ConfiguresRecurring concern (pure nested RecurringYAML); rails_pulse keeps identical behavior.\n\n```json:metadata\n{\"files\": [\"lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb\", \"lib/generators/pu/lite/rails_pulse/rails_pulse_generator.rb\", \"test/generators/configures_recurring_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/configures_recurring_test.rb test/generators/lite_generators_test.rb\", \"acceptanceCriteria\": [\"ConfiguresRecurring autoloads and exposes add_recurring_tasks(tasks_yaml, marker:)\", \"RecurringYAML tested for env-scoped and flat layouts\", \"rails_pulse uses concern, old private method removed, tests still pass\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 2: pu:lite:tune generator (SQLite pragmas)",
+      "status": "completed",
+      "description": "Generator that inserts tuned, version-aware performance pragmas into config/database.yml default block, idempotently.\n\n```json:metadata\n{\"files\": [\"lib/generators/pu/lite/tune/tune_generator.rb\", \"test/generators/lite_generators_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/lite_generators_test.rb\", \"acceptanceCriteria\": [\"TuneGenerator < Rails::Generators::Base, includes Generator\", \"Rails 8.1+ block = four deltas, no baseline, no busy_timeout\", \"Rails <8.1 also includes baseline pragmas\", \"idempotent re-run\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 3: pu:lite:maintenance generator (job + schedule)",
+      "status": "completed",
+      "blockedBy": [1],
+      "description": "Generator that installs app/jobs/sqlite_maintenance_job.rb and schedules it in config/recurring.yml via ConfiguresRecurring.\n\n```json:metadata\n{\"files\": [\"lib/generators/pu/lite/maintenance/maintenance_generator.rb\", \"lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt\", \"test/generators/lite_generators_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/lite_generators_test.rb\", \"acceptanceCriteria\": [\"MaintenanceGenerator includes Generator + ConfiguresRecurring\", \"--schedule option defaults to 'every day at 3:30am'\", \"job template defines MaintenanceConnection/OPTIMIZE_DBS/VACUUM_DBS, PRAGMA optimize + VACUUM, Rails.error.report\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 4: Wire generators into lite.rb app template",
+      "status": "completed",
+      "blockedBy": [2, 3],
+      "description": "lite app template runs pu:lite:tune after setup and pu:lite:maintenance after the solid/rails_pulse stack, each with a commit guard. Only edit public source.\n\n```json:metadata\n{\"files\": [\"docs/public/templates/lite.rb\"], \"verifyCommand\": \"ruby -c docs/public/templates/lite.rb\", \"acceptanceCriteria\": [\"tune generated after setup with commit guard\", \"maintenance generated after rails_pulse with commit guard\", \"only public/templates/lite.rb edited\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 5: Docs page + sidebar entry",
+      "status": "completed",
+      "description": "Add docs/reference/generators/lite.md documenting both generators and link it in the VitePress sidebar.\n\n```json:metadata\n{\"files\": [\"docs/reference/generators/lite.md\", \"docs/.vitepress/config.ts\"], \"verifyCommand\": \"yarn docs:build\", \"acceptanceCriteria\": [\"lite.md documents both generators with rationale\", \"sidebar links /reference/generators/lite\", \"docs build passes with no broken links\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 6,
+      "subject": "Task 6: Full suite + single final commit",
+      "status": "pending",
+      "blockedBy": [1, 2, 3, 4, 5],
+      "description": "Run full generator test suite, then make ONE commit with all changes (per user's 'commit at the end').\n\n```json:metadata\n{\"files\": [], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/lite_generators_test.rb test/generators/configures_recurring_test.rb\", \"acceptanceCriteria\": [\"generator tests pass on Rails 8.1\", \"single commit contains all generators, concern, refactor, template, docs\"], \"requiresUserVerification\": false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-06-04"
+}

data/docs/superpowers/specs/2026-06-01-structured-inputs-design.md

@@ -0,0 +1,191 @@
+# Structured Inputs
+
+**Date:** 2026-06-01 (updated 2026-06-02)
+**Status:** Approved — DSL name `structured_input` final; ready for implementation plan
+
+## Problem
+
+There is no first-class way to collect a **structured input** — a group of
+fields gathered into one object, or a variable-length list of such objects —
+without an ActiveRecord association behind it:
+
+- **Interactions** declare scalar `attribute`s only. They cannot collect a
+  structured object (`address => {street:, city:}`) or a list of them. The
+  included `nested_input` is model-backed and silently renders nothing for the
+  classless case (characterized in
+  `test/plutonium/ui/form/interaction_nested_input_test.rb`).
+- **Resources** can edit a JSON/jsonb column only as a raw JSON textarea or a
+  flat `key_value_store` — no structured UI for `{a, b}` or `[{a, b}, …]` stored
+  in a JSON column. Association-backed repetition is `nested_input`'s job; JSON
+  columns have nothing.
+
+## Goal
+
+One DSL — **`structured_input`** — for a *classless* group of fields, collected
+as:
+
+- a **hash** (single object) by default, or
+- an **array of hashes** when `repeat:` is given (the repeater),
+
+rendered with a fields group, and feeding either an **interaction attribute** or
+a **resource JSON column**. The single object is the base; the repeater is the
+same group rendered N times.
+
+### Non-goals
+
+- Type coercion of values. Rows/objects are plain hashes; the host validates.
+- Replacing model-backed `nested_input` (stays the resource association feature).
+
+## Feasibility anchors
+
+This design follows the grain of phlexi-form rather than fighting it:
+
+1. **`nest_one` → hash, `nest_many` → array.** The library's own
+   `extract_input` already produces exactly these shapes, and `nest_many` is
+   literally `nest_one` repeated:
+
+   ```ruby
+   # Namespace#extract_input (nest_one):   { key => { field => value, … } }
+   # NamespaceCollection#extract_input (nest_many):
+   params = params[key]
+   params = params.values if params.is_a?(Hash)        # index-hash → array, free
+   { key => Array(params).map { |p| namespace.extract_input([p]) } }
+   ```
+
+2. **Hash-backed rendering.** `Phlexi::Field::Support::Value.from` reads
+   `object[key]` for a `Hash`, so a row/object is a plain hash and the blank
+   template is `{}`. No synthesized classes.
+
+3. **Form-driven param extraction.** Plutonium extracts submitted resource
+   params via `build_form(record).extract_input(params)`
+   (`controller.rb#submitted_resource_params`). Nesting with `as: :<name>` makes
+   the extracted hash/array land under `:<name>`, which assigns **directly** to
+   the JSON column / interaction attribute — no `_attributes=` setter, no manual
+   strong-params.
+
+## Design
+
+### 1. The DSL — `structured_input`
+
+```ruby
+# single → hash
+structured_input :address do |f|
+  f.input :street
+  f.input :city
+end
+# value: address => { street:, city: }
+
+# repeater → array of hashes (max 10 rows)
+structured_input :contacts, repeat: 10 do |f|
+  f.input :label
+  f.input :phone_number
+end
+# value: contacts => [ { label:, phone_number: }, … ]
+```
+
+- `repeat:` semantics: **`repeat: <int>` = maximum rows**; `repeat: true` =
+  repeater with the default cap; **absent = single** (hash). Presence of
+  `repeat:` always means an array — `repeat: 1` is "array, max one row", *not*
+  the single form.
+- Fields come from a block or `using:`/`fields:` (the existing lightweight
+  `NestedInputsDefinition` holder, `defineable_props :field, :input`).
+- Registers config in a `defined_structured_inputs` registry, via a shared
+  module included by both resource definitions (`Plutonium::Definition::Base`)
+  and interactions (`Plutonium::Interaction::Base`) — both already mix in
+  `DefineableProps`.
+
+### 2. Rendering (shared, classless)
+
+The unit is the **fields group** — the declared inputs rendered over a nested
+builder. Single and repeater differ only in `nest_one` vs `nest_many` and the
+surrounding chrome:
+
+- **Single:** `nest_one(:address, as: :address)` over the current value (or `{}`)
+  → one fieldset of inputs. No add/remove chrome, no `<template>`, no hidden
+  `id`/`_destroy`.
+- **Repeater:** `nest_many(:contacts, as: :contacts)` → the existing repeater
+  chrome (the `nested-resource-form-fields` Stimulus controller, `limit` = the
+  `repeat` cap, a `<template>` holding a blank `{}` row, existing rows from the
+  array value, an add button, a per-row delete control). No hidden `id`/`_destroy`.
+
+This reuses the same Stimulus controller and visual structure as the model-backed
+repeater, but is a **separate classless code path**. Model-backed `nested_input`
+rendering is untouched (still covered by
+`test/integration/admin_portal/nested_form_rendering_test.rb`).
+
+### 3. Param flow (shared)
+
+- Nesting with `as: :<name>` → `extract_input` yields `{name => {…}}` (single) or
+  `{name => [{…}, …]}` (repeater, index-hash already normalized to array).
+- The value assigns **directly** to the JSON column / interaction attribute.
+- A shared **clean step**, keyed off `defined_structured_inputs`, runs
+  post-extract: for repeaters, drop all-blank rows and strip `_destroy`; single
+  passes through. Rows are positional — **no ids**.
+
+### 4. Host — interactions
+
+`structured_input :name` declares `attribute :name` defaulting to `{}` (single)
+or `[]` (repeater). The extracted+cleaned value flows into the attribute;
+`execute` sees a hash or an array.
+
+### 5. Host — resources (JSON, no model macro)
+
+Because it is classless, the resource side needs **no `accepts_nested_attributes_for`-style
+model declaration** — just:
+
+- **Model:** a `json`/`jsonb` column named `name`.
+- **Definition:** `structured_input :name …`.
+- **Policy:** permit `:name` in `permitted_attributes_for_*` so the form renders
+  it.
+
+Params then flow via the form's `extract_input` → clean → `record.name = hash/array`
+→ persisted in the JSON column. The `nested_input` model/definition split
+dissolves here; classless JSON needs only the column + the definition DSL.
+
+### 6. Remove the broken nested surface from interactions
+
+- `nested_input` is **removed** from interactions (`Interaction::Base` stops
+  mixing in `Plutonium::Definition::NestedInputs`) → `NoMethodError` at
+  class-load. `defined_nested_inputs` is likewise undefined; the inherited form
+  branch is guarded by `respond_to?` and simply skips.
+- `accepts_nested_attributes_for` is **removed** from interactions
+  (`Interaction::Base` stops mixing in `Plutonium::Interaction::NestedAttributes`).
+  Build models explicitly in `execute` if ever needed.
+
+Resources keep both model-backed `nested_input` and AR `accepts_nested_attributes_for`
+unchanged, and additionally gain `structured_input`.
+
+## Testing
+
+- **Clean step** (unit): array and index-keyed-hash → array; all-blank rows
+  dropped; `_destroy` stripped; single passes through; no ids.
+- **Single** (interaction + resource): renders one fieldset; round-trip → a hash
+  value on the attribute / JSON column.
+- **Repeater** (interaction + resource): renders the repeater chrome with
+  `host[contacts][NEW_RECORD][label]` naming, add/delete, no hidden id/`_destroy`;
+  round-trip → an array value; blank rows rejected; edit repopulates.
+- **Guard** (unit): interactions do not respond to `nested_input` /
+  `accepts_nested_attributes_for` / `defined_nested_inputs` (replaces the current
+  `interaction_nested_input_test.rb`).
+- **Regression**: resource `nested_input` unchanged — existing characterization
+  tests stay green.
+- Fixtures via the `pu:*` generators; the resource fixture uses a JSON column.
+
+## Open questions (resolve in plan)
+
+- **Clean-step placement:** one shared function, two call sites (the resource
+  controller param path; the interaction's param assignment). Confirm the exact
+  hooks.
+- **Field naming:** `as: :<name>` (direct assignment, recommended) vs a
+  `_attributes` suffix. Verify no collision with form/extract internals.
+- **JSON column type in the dummy fixture:** SQLite `json`/serialized text for
+  the test; document `jsonb` as the production recommendation.
+
+## Risk / breaking change
+
+- Removing `nested_input` + `accepts_nested_attributes_for` from interactions is
+  a deliberate breaking change; the only previously-working case (an interaction
+  mirroring a real resource association) is redundant with resource forms.
+  Offenders get a `NoMethodError` naming the method; the README is reworked to
+  `structured_input`.
+- `structured_input` is additive on resources and new on interactions.

data/docs/superpowers/specs/2026-06-04-sqlite-tune-maintenance-generators-design.md

@@ -0,0 +1,238 @@
+# SQLite Tuning & Maintenance Generators — Design
+
+**Date:** 2026-06-04
+**Status:** Approved (design); pending implementation plan
+
+## Summary
+
+Port two production-proven SQLite improvements from `radioactive_labs/universal_chatbot`
+into the Plutonium generator template:
+
+1. **Config tuning** — performance pragmas in `config/database.yml`.
+2. **Maintenance** — a scheduled `SqliteMaintenanceJob` (`PRAGMA optimize` everywhere,
+   `VACUUM` on safe databases only).
+
+Both ship as **two new generators** under the existing `pu:lite` namespace:
+`pu:lite:tune` and `pu:lite:maintenance`. The existing `pu:lite:setup` generator is
+left untouched.
+
+## Background
+
+### What the reference project does
+
+`config/database.yml` `default: &default` block carries tuned pragmas:
+
+```yaml
+pragmas:
+  cache_size: -64000           # 64 MB page cache (default ~2 MB is too small)
+  temp_store: 2                # MEMORY — sorts/temp indexes stay off disk
+  mmap_size: 536870912         # 512 MB (override the 128 MB default)
+  wal_autocheckpoint: 10000    # checkpoint every ~40 MB of WAL, fewer pauses
+```
+
+It deliberately does **not** set `busy_timeout` — Rails routes the `timeout:` key to
+the sqlite3 gem's constant-poll `busy_handler_timeout`, which has better tail-latency
+than SQLite's internal backoff. Adding `busy_timeout` to pragmas would replace that with
+the worse handler.
+
+`app/jobs/sqlite_maintenance_job.rb` runs nightly via `config/recurring.yml`:
+
+- Uses an isolated abstract connection class (`MaintenanceConnection`) so it never
+  mutates the global primary connection that sibling jobs rely on.
+- `PRAGMA optimize` on all databases (cheap, brief shared lock).
+- `VACUUM` only on databases without live 24/7 writers. Excludes `queue`/`cache`/`cable`
+  because SolidQueue / Solid Cache / Solid Cable write to them constantly, and VACUUM's
+  global exclusive lock stalls and errors those processes (e.g. SolidQueue process
+  deregistration hitting "database is locked"). This is the `2b813bdd` fix
+  ("stop nightly VACUUM from locking the live queue DB").
+- Errors are reported via `Rails.error.report` and the connection is always removed in
+  an `ensure` block.
+
+### Current Plutonium state
+
+- `pu:lite:setup` only ensures the `sqlite3` gem version and adds the Rails 7 enhanced
+  adapter. **No pragma tuning.**
+- `pu:lite:*` generators (solid_queue, solid_cache, solid_cable, solid_errors,
+  rails_pulse, litestream) wire up extra databases via the `ConfiguresSqlite` concern.
+- `rails_pulse_generator.rb` already contains working, env-aware `config/recurring.yml`
+  injection logic (handles both env-scoped and flat recurring files).
+- **No pragma tuning and no maintenance job exist in the template today.**
+
+## Design Decisions (confirmed)
+
+| Decision | Choice |
+|---|---|
+| Packaging | Two new generators: `pu:lite:tune`, `pu:lite:maintenance`. `pu:lite:setup` untouched. |
+| Pragma values | Port reference values **verbatim**. |
+| VACUUM target selection | Editable list in the generated job; runtime confirms each DB exists (`configs_for ... return unless config`); user can extend the list. |
+| `recurring.yml` editing | Extract the rails_pulse injection logic into a shared `ConfiguresRecurring` concern; rails_pulse refactored to use it. |
+| Generator names | `pu:lite:tune` and `pu:lite:maintenance` (confirmed). |
+
+## Component 1: `pu:lite:tune`
+
+**File:** `lib/generators/pu/lite/tune/tune_generator.rb`
+
+**Purpose:** Insert tuned performance pragmas into `config/database.yml`'s
+`default: &default` block.
+
+**Behavior:**
+
+- Locate the `default: &default` mapping in `config/database.yml`.
+- If a `pragmas:` key already exists under `default`, merge our keys, skipping any key
+  already present (no clobbering user values).
+- If no `pragmas:` key exists, insert a new `pragmas:` block containing the four reference
+  deltas plus the reference's explanatory comments, including the `busy_timeout` note.
+- **Version-aware pragma set:**
+  - Rails **8.1+**: write only the four deltas (`cache_size`, `temp_store`, `mmap_size`,
+    `wal_autocheckpoint`) — Rails already sets WAL / synchronous=NORMAL / foreign_keys /
+    mmap=128MB / journal_size_limit by default.
+  - Rails **< 8.1**: also emit the baseline set (`journal_mode: WAL`,
+    `synchronous: NORMAL`, `foreign_keys: true`, `journal_size_limit`) since these are not
+    guaranteed there. The Rails 7 path already pulls in
+    `activerecord-enhancedsqlite3-adapter` via `pu:lite:setup`, which supports pragmas.
+- **Idempotent:** re-running skips keys already present; a marker (the comment header or
+  the presence of our keys) prevents duplicate insertion.
+- Emits `say_status` lines for each key added.
+
+**Reuse:** YAML location/insertion can lean on the existing `ConfiguresSqlite` concern's
+file-manipulation helpers (`insert_into_file`, regex anchors) and `file_includes?`. The
+default-block anchor is matched the same way the concern matches `default: &default`.
+
+## Component 2: `pu:lite:maintenance`
+
+**File:** `lib/generators/pu/lite/maintenance/maintenance_generator.rb`
+**Template:** `lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt`
+
+**Purpose:** Install `SqliteMaintenanceJob` and schedule it in `config/recurring.yml`.
+
+**Behavior:**
+
+- `template` the job to `app/jobs/sqlite_maintenance_job.rb`, ported from the reference:
+  - Isolated `MaintenanceConnection < ActiveRecord::Base` (`abstract_class = true`).
+  - `OPTIMIZE_DBS` and `VACUUM_DBS = %w[primary errors rails_pulse]` as **editable
+    constants**, with comments instructing the user to add their own DB names.
+  - At runtime, `configs_for(env_name:, name:, include_hidden: true)` returns the config
+    or nil; `return unless config` silently skips DBs that don't exist — this is the
+    "keep a list, confirm they exist" behavior.
+  - `PRAGMA optimize` on every `OPTIMIZE_DBS` entry; `VACUUM` only on `VACUUM_DBS`.
+  - Preserve the live-writer exclusion rationale (queue/cache/cable) as comments.
+  - `rescue => e` → `Rails.error.report(e, context: {...})`; `ensure` removes the
+    connection.
+- Add the recurring entry to `config/recurring.yml` using the shared
+  `ConfiguresRecurring` concern (see below):
+  ```yaml
+  sqlite_maintenance:
+    class: SqliteMaintenanceJob
+    queue: default
+    schedule: every day at 3:30am
+    description: "VACUUM + PRAGMA optimize across SQLite databases"
+  ```
+- **Gating:** if solid_queue is not installed or `config/recurring.yml` is absent, still
+  write the job file but log that no scheduler was found (mirrors rails_pulse's
+  `solid_queue_installed?` gate).
+- **Idempotent:** skip the recurring injection if `sqlite_maintenance` is already present;
+  `template` with conflict handling for the job file.
+
+## Component 3: `ConfiguresRecurring` concern (refactor)
+
+**File:** `lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb`
+
+Extract the env-aware `recurring.yml` injection currently private to
+`rails_pulse_generator.rb` into a reusable concern. Concerns are autoloaded by Zeitwerk
+(`Zeitwerk::Loader.for_gem` in `lib/generators/pu/lib/plutonium_generators.rb`), so a new
+file at the conventional path with module nesting
+`PlutoniumGenerators::Concerns::ConfiguresRecurring` is picked up automatically — no
+manual `require` needed. Public surface:
+
+```ruby
+# Inject one or more recurring task blocks into config/recurring.yml,
+# handling both env-scoped (production:/development:) and flat layouts.
+add_recurring_tasks(tasks_yaml, marker:)
+```
+
+- `tasks_yaml`: the YAML body for the task(s), without leading indentation (the concern
+  re-indents per environment, as the existing code does).
+- `marker`: a string used for the `file_includes?` idempotency guard (e.g.
+  `"rails_pulse"`, `"sqlite_maintenance"`).
+- Internals are the existing `inject_*_under_envs` / indent-detection logic, generalized
+  to accept arbitrary task YAML instead of hardcoded rails_pulse tasks.
+
+`rails_pulse_generator.rb` is refactored to call `add_recurring_tasks` with its existing
+task YAML and `marker: "rails_pulse"`. No behavior change.
+
+## Testing
+
+Add to `test/generators/` (alongside `lite_generators_test.rb`,
+`configures_sqlite_test.rb`):
+
+- **`pu:lite:tune`:**
+  - Inserts the `pragmas:` block with the four delta keys into the `default` anchor.
+  - Re-running is idempotent (no duplicate keys).
+  - Merges into an existing `pragmas:` block without clobbering user-set keys.
+  - (If feasible in the harness) version-aware: Rails < 8.1 emits the baseline set.
+- **`pu:lite:maintenance`:**
+  - Creates `app/jobs/sqlite_maintenance_job.rb` with the expected constants.
+  - Injects the `sqlite_maintenance` entry under each environment in an env-scoped
+    `recurring.yml`; idempotent on re-run.
+  - When `recurring.yml` is absent, writes the job and logs the missing-scheduler notice.
+- **`ConfiguresRecurring`:** the extracted concern behaves identically to the old
+  rails_pulse path (regression guard) — verify via the existing rails_pulse test still
+  passing plus a focused concern test.
+
+## App template integration (`lite.rb`)
+
+`docs/public/templates/lite.rb` is the SQLite-stack app template that chains the
+`pu:lite:*` generators `after_bundle` (setup → solid_queue/cache/cable/errors →
+litestream → rails_pulse), each followed by a conditional git commit.
+
+Wire **both** new generators into this template, matching the existing pattern (each with
+its own `git add` / `git commit` guard):
+
+- `pu:lite:tune` — immediately after `pu:lite:setup` (pragmas belong with the base SQLite
+  config, before the extra DBs are added).
+- `pu:lite:maintenance` — after the solid stack and rails_pulse, so the extra databases
+  exist and `solid_queue` is present for scheduling.
+
+Only edit the source template at `docs/public/templates/lite.rb`; the copies under
+`docs/dist/` and `docs/.vitepress/dist/` are build artifacts regenerated by
+`yarn docs:build`.
+
+## Documentation
+
+- New standalone page **`docs/reference/generators/lite.md`** describing the `pu:lite:*`
+  generators, with full sections for `pu:lite:tune` and `pu:lite:maintenance` (purpose,
+  options, idempotency, the `busy_timeout` rationale, and the VACUUM live-writer
+  exclusion rationale). Documenting the other existing `pu:lite:*` generators on this page
+  is a nice-to-have but the two new ones are required.
+- Add the new page to the VitePress sidebar in `docs/.vitepress/config.ts` (near the
+  existing `/reference/app/generators` entry) so it is reachable.
+- Skills require a gem release to take effect; a skill update is **out of scope** for this
+  change (docs page + sidebar only).
+
+## Out of scope (YAGNI)
+
+- App-specific extras from the reference (`sqlite_vec` extension loading, per-app
+  cleanup jobs, Rails Pulse summary/cleanup jobs) — those belong to their own generators
+  or the app, not this port.
+- Changing `pu:lite:setup` behavior.
+- Litestream / backup concerns (separate `pu:lite:litestream` generator already exists).
+
+## File change list
+
+| Action | Path |
+|---|---|
+| Create | `lib/generators/pu/lite/tune/tune_generator.rb` |
+| Create | `lib/generators/pu/lite/maintenance/maintenance_generator.rb` |
+| Create | `lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt` |
+| Create | `lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb` |
+| Modify | `lib/generators/pu/lite/rails_pulse/rails_pulse_generator.rb` (use shared concern) |
+| Modify | `docs/public/templates/lite.rb` (chain `pu:lite:tune` + `pu:lite:maintenance`) |
+| Create | `test/generators/tune_generator_test.rb` (or extend `lite_generators_test.rb`) |
+| Create | `test/generators/maintenance_generator_test.rb` (or extend `lite_generators_test.rb`) |
+| Create | `docs/reference/generators/lite.md` |
+| Modify | `docs/.vitepress/config.ts` (sidebar entry for the new page) |
+
+> Zeitwerk autoloads concerns by path, so no edit to
+> `lib/generators/pu/lib/plutonium_generators.rb` is required for the new concern.
+> The `docs/dist/` and `docs/.vitepress/dist/` copies of `lite.rb` are build artifacts —
+> do not hand-edit them.

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.52.0)
+    plutonium (0.55.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.52.0)
+    plutonium (0.55.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.53.1)
+    plutonium (0.55.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/core/update/update_generator.rb

@@ -23,7 +23,10 @@ module Pu
         return unless File.file?(Rails.root.join(".claude", "skills", "plutonium", "SKILL.md"))
 
         say_status :update, "Syncing Plutonium Claude skills...", :green
-        Rails::Generators.invoke("pu:skills:sync", [], destination_root: Rails.root)
+        # Shell out to a fresh process so the sync reads the newly-installed
+        # gem's skills. Invoking in-process would reuse the already-loaded
+        # (pre-update) gem, whose Plutonium.root still points at the old skills.
+        run "bin/rails generate pu:skills:sync"
       end
 
       def update_gem

data/lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PlutoniumGenerators
+  module Concerns
+    module ConfiguresRecurring
+      ENV_KEYS = %w[production development staging test].freeze
+
+      # Pure transform of a config/recurring.yml string. No file IO — testable
+      # in isolation, mirroring ConfiguresSqlite::DatabaseYAML.
+      class RecurringYAML
+        # Returns new content with `tasks_yaml` injected. If the file is
+        # env-scoped (has top-level production:/development:/... keys), the
+        # tasks are inserted under each environment at the siblings' indent.
+        # Otherwise they are appended at column 0.
+        def inject(content, tasks_yaml)
+          if env_scoped?(content)
+            inject_under_envs(content, tasks_yaml)
+          else
+            content.rstrip + "\n\n" + indent(tasks_yaml, 0)
+          end
+        end
+
+        private
+
+        def env_scoped?(content)
+          content.lines.any? { |l| l.match?(env_re) }
+        end
+
+        def env_re
+          /^(#{ENV_KEYS.join("|")}):\s*$/
+        end
+
+        def indent(yaml, n)
+          pad = " " * n
+          yaml.gsub(/^(?=.)/, pad)
+        end
+
+        def inject_under_envs(content, tasks_yaml)
+          lines = content.lines
+          env_starts = lines.each_with_index.select { |l, _| env_re.match?(l) }.map(&:last)
+
+          env_starts.reverse_each do |start|
+            end_idx = lines.length
+            ((start + 1)...lines.length).each do |i|
+              if lines[i].match?(/^[^\s#]/)
+                end_idx = i
+                break
+              end
+            end
+
+            child_indent = 2
+            ((start + 1)...end_idx).each do |i|
+              if (m = lines[i].match(/^(\s+)\S/))
+                child_indent = m[1].length
+                break
+              end
+            end
+
+            insert_at = end_idx
+            while insert_at > start + 1 && lines[insert_at - 1].strip.empty?
+              insert_at -= 1
+            end
+
+            lines.insert(insert_at, "\n", indent(tasks_yaml, child_indent))
+          end
+
+          lines.join
+        end
+      end
+
+      private
+
+      # Inject recurring task YAML into config/recurring.yml. Returns true when
+      # written, false when the file is missing or the marker already present
+      # (idempotent). `marker` is matched with file_includes? to avoid dupes.
+      def add_recurring_tasks(tasks_yaml, marker:)
+        recurring_file = "config/recurring.yml"
+        full_path = File.expand_path(recurring_file, destination_root)
+        return false unless File.exist?(full_path)
+        return false if file_includes?(recurring_file, marker)
+
+        new_content = RecurringYAML.new.inject(File.read(full_path), tasks_yaml)
+        create_file recurring_file, new_content, force: true
+        say_status :recurring, "#{marker} (config/recurring.yml)"
+        true
+      end
+    end
+  end
+end

data/lib/generators/pu/lite/maintenance/maintenance_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../../lib/plutonium_generators"
+
+module Pu
+  module Lite
+    class MaintenanceGenerator < Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+      include PlutoniumGenerators::Concerns::ConfiguresRecurring
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install a nightly SqliteMaintenanceJob (PRAGMA optimize + VACUUM)"
+
+      class_option :schedule, type: :string, default: "every day at 3:30am",
+        desc: "Cron-style schedule for the maintenance job"
+
+      def start
+        template "app/jobs/sqlite_maintenance_job.rb"
+
+        if gem_in_bundle?("solid_queue")
+          unless add_recurring_tasks(maintenance_task_yaml, marker: "sqlite_maintenance")
+            log :skip, "could not schedule (config/recurring.yml missing or already scheduled)"
+          end
+        else
+          log :info, "solid_queue not found — job installed but not scheduled. Add a 'sqlite_maintenance' entry to your scheduler."
+        end
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def maintenance_task_yaml
+        <<~YAML
+          sqlite_maintenance:
+            class: SqliteMaintenanceJob
+            queue: default
+            schedule: "#{options[:schedule]}"
+            description: "VACUUM + PRAGMA optimize across SQLite databases"
+        YAML
+      end
+    end
+  end
+end