studio-engine 0.33.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ed77550c057e9ec4e232cc40ea934ef4753cc1d73d30e98b52c0a56f7ad8c8d
-  data.tar.gz: 01b04c9da431ef4d43b75cf12533c3aece29c5557157af4c0f91eadf1fe9e2bb
+  metadata.gz: dc5fc673a7b9d072c93f482c90919c0f26836bd5e90194691ca30b5beb7c22d4
+  data.tar.gz: 9cbedec8a84b9619061217f90bceadbd51485e691351233bb67af6f03231b76e
 SHA512:
-  metadata.gz: a1b26944f9f08b070f00aec356cc2435e3e35096d1353c970dd797b486293e50827fa6e6a11b3bc67ea306ef505f740114640595a4db10da4e9883a71561633b
-  data.tar.gz: ce46eddd0627c5eae83daa9fc2eca518d74eae7500ce0e44a22faf016c0059d68b01f1d7b874e1f38d063918c460d36bf981d33b2a7f5dc3fe07ac6e0db85811
+  metadata.gz: '088bca3db79b1ad97d52bf2478aa08518a6139e73c700cc63d30903c1d31e4fddb391213c2061cd0711d0d5656a7115e53dd10817b094271c459543133e36ea7'
+  data.tar.gz: 96eb836f896ed9a12dd8c71a308178aa112387bc40f266323dad82db726df9698a4881ff4450c7fa7ce9f42d61cf1bcab9ca80a88940f243891e1cfe0307f3d0

data/CHANGELOG.md

@@ -2,6 +2,228 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.37.0 — 2026-08-10
+
+### Added
+- Standard transactional email primitive with a registry-backed catalog, and the
+  email preview folded into that registry.
+
+### Fixed
+- The crop confirm is guarded by owner, so one confirmed crop can no longer fan out
+  and overwrite every row's banner on /admin/emails.
+
+## 0.36.0 — 2026-08-10
+
+**Transactional emails become an engine primitive.** Every consuming app now
+ships working, branded transactional email the moment it boots, and can grow its
+own workflows and artwork. Additive — no host change is required to take this
+release.
+
+**`Studio::EmailImage` is now a registry.** It was a one-entry `VARIANTS` hash;
+it is now a host-declared registry following the `Studio::ModelPage.register`
+precedent. A registered email is mostly symbolic of a workflow — a key, a label,
+a description — and its only real asset is its banner image.
+
+- The engine **pre-registers the two every Studio app sends**, `magic_link` and
+  `email_change_confirmation`, so a host inherits both without declaring
+  anything.
+- A host registers its own from an initializer:
+  `Studio::EmailImage.register("winnings", label: "Contest winnings")`.
+  Re-registering an inherited key **updates it in place**, keeping its page
+  position and its inherited artwork.
+- `variants`, `label`, `known?`, `record`, `url`, and `store` keep their old
+  shapes, so `Studio::EmailImage.url(:magic_link)` — the only external caller
+  today — is untouched.
+
+**Inheritance with per-app override.** Resolution is now two-layered:
+
+```
+resolved_url(:magic_link)  ->  this app's ImageCache row (its own S3 bucket)  app-owned
+                           ->  the engine's default gem asset                 inherited
+                           ->  nil                                            bannerless
+```
+
+`resolved_url`, **not** `url`. `url` deliberately keeps its pre-registry meaning —
+this app's own image, or nil — so a caller written before the registry keeps the
+behavior it was built against. A mailer that falls back itself
+(`url(...) || own_banner`) must stay on `url`; switching it to `resolved_url`
+would make that fallback dead code and replace the app's own artwork with the
+engine default.
+
+Defaults **ride the gem** (`app/assets/images/emails/*`), so a brand-new app with
+an empty bucket sends good-looking email on day one with no cross-app S3
+permission. Uploading writes to that app's own bucket and its own `image_caches`
+row — which is exactly "the asset now belongs to this app". Placeholder artwork
+ships for both standard emails; real artwork lands in a later release.
+
+**New: `/admin/emails`**, modelled on the living style guide — one shared engine
+page, admin-gated, rendering inside each host's layout.
+
+**It is OPT-IN, and must be.** Add to `config/initializers/studio.rb`:
+
+```ruby
+config.draw_admin_emails_routes = true
+```
+
+`turf-monster` already owns `/admin/emails` (its `EmailCatalog` manager:
+`namespace :admin { get "emails", as: :emails }`) and therefore both helper
+names, `admin_emails_path` and `admin_email_path`. Drawing the engine's page
+unconditionally raises `ArgumentError: Invalid route name, already in use:
+'admin_emails'` *while turf-monster's own routes are loading*, which takes down
+its **entire** route set — every `admin_*_path` in the app goes undefined. A host
+cannot opt out of a failure that happens before its config is read, so the
+default is off until no consumer owns the name.
+
+The gate covers only the **page**. The registry and the inherited-default
+resolution are always on, and the engine's `UserMailer` already calls
+`resolved_url`, so an app sends branded email whether or not it draws the page.
+
+**`/admin/email_images` is deprecated, not deleted.** It still renders, and its
+`admin_email_images_path` / `admin_email_image_path` helpers still resolve —
+`mcritchie-studio` and `turf-monster` both have tests on `main` that drive it,
+and consumer CI runs each consumer's default branch. A later engine minor deletes
+the controller, view, and routes once no consumer references them. In the
+meantime the old page had its own reporting bug fixed too: it now reads
+`preview_url`, so it no longer claims "No image yet" about an email that is
+visibly sending one.
+
+- The table is the primary view: **name + live image on every row**, so an email
+  is identifiable at a glance.
+- Each row says whether the live image is the **inherited default** or
+  **app-owned**, and an app-owned image can be reverted back to the default.
+- Uploading goes through the **standard crop modal**, not a bare file input.
+
+**Fix — the page misreported what was actually shipping.** It read only the S3
+override, so it announced *"No image yet — emails send without a banner until you
+upload one"* for an email that was visibly sending a banner from a committed repo
+asset. `current_url` now resolves what really ships, and the copy distinguishes
+"inherited default" from "no image at all".
+
+**New: `Studio.s3_key_prefix`** — an optional key namespace inside the bucket, so
+a satellite app can share an already-provisioned bucket instead of standing up
+its own pair:
+
+```ruby
+config.s3_bucket_prefix = "mcritchie-studio"
+config.s3_key_prefix    = "mcritchie-industries/"
+# -> s3://mcritchie-studio-dev/mcritchie-industries/email_banners/...
+```
+
+`Studio::S3` applies it to `upload`, `download`, `url`, `signed_url`, `exists?`,
+`delete`, and `list` — callers keep passing logical keys and never see it, and
+`list` strips it back off so a result feeds straight into `download`/`url`.
+**Unset by default, so every already-shipped app's keys are byte-identical.**
+Also new: `Studio::S3.configured?`, for callers that must degrade rather than
+rescue `NotConfigured`.
+
+**Honest degradation.** An app whose host never set `s3_bucket_prefix` renders
+`/admin/emails` **read-only** — showing the inherited defaults it is genuinely
+sending, naming the one setting that turns uploads on — instead of 500ing on the
+first upload.
+
+**New partial: `studio/modals/scoped_host`** — a self-contained modal host on its
+own Alpine store, for a page that must bring its own modals. `/admin/emails` uses
+it (`store: "emailModals"`) to ship its crop + saving modals, so the page works
+identically in an app that renders a shared modal host and one that renders none
+at all. `imageUploadHost` and `submitFormWithProgress` gained a matching `store`
+option (default `"modals"`, so existing call sites are unchanged); the crop-photo
+and saving partials already had one.
+
+It is a **separate partial rather than a local on `studio/modals/_host`** for a
+reason worth knowing: this is a non-isolated engine, so an app view at the same
+path shadows the engine's — and `mcritchie-studio` and `turf-monster` both ship
+their own `app/views/studio/modals/_host.html.erb`. A page rendering
+`studio/modals/host` in those apps silently gets the app's fork, which knows
+nothing of a `store:` local, so the page-scoped store is never registered and
+every modal trigger on the page does nothing. `scoped_host` is unforked in every
+app. The living style guide's hand-rolled `dsModals` host can rebase onto it.
+
+Register modals with `current()?.id`, not `current().id` — the outer template
+unmounts one tick after the stack empties, so a bare `.id` throws on close.
+
+**Compatibility.** `Studio::EmailImage.url(key)` keeps its **pre-registry
+contract** — this app's own uploaded image, or `nil`. The two-layer resolution
+lives in the new `resolved_url(key)`. This matters: `turf-monster`'s mailer is
+`Studio::EmailImage.url(:magic_link) || email_banner_url("magic-link-banner.jpg")`,
+and making `url` resolve to the engine default would have turned that `||` into
+dead code and silently replaced turf-monster's committed branded banner with the
+engine's **placeholder** in live sign-in email. A method whose signature is
+unchanged but whose return value flips from `nil` to a value is not additive.
+
+**Consumer note.** Nothing here is required to upgrade. To adopt: set
+`config.draw_admin_emails_routes = true`, link `admin_emails_path` from the app's
+admin sidebar, register any extra workflows, switch mailers from `url` to
+`resolved_url` where you want the inherited default, and drop any local
+`branded_mailer.html.erb` fork — the engine's copy is app-name-aware through
+`Studio.app_name`.
+
+**The local-review link now signs the reviewer in as someone who can SEE the
+page.** `/_studio/local_review` — the local half of the task board's WAITING
+APPROVAL button — provisions the account before it mints, at the new
+`Studio.local_review_role` (default `"admin"`).
+
+The board hands this endpoint the operator's **production** email address. A
+fresh worktree database has never seen it, so consuming the link took
+`Studio::LinkConsumption#sign_up_new` and created the account at the default
+role, `viewer`. `require_admin` on the page under review then redirected it to
+`/`. The sign-in **succeeded** every time, which is what kept this quiet: the
+button worked, the token was valid, and the operator simply arrived on the home
+page having never seen the thing he was asked to review. A seeded admin
+(`alex@mcritchie.studio`) worked fine, so only his real address ever hit it.
+
+The endpoint now find-or-creates the reviewer and ensures the role BEFORE
+minting, so the consume takes `sign_in_existing` onto an account that already
+has rights. An existing account is promoted, never duplicated; an already-correct
+one is not rewritten.
+
+New public config:
+
+```ruby
+Studio.configure do |config|
+  config.local_review_role = "admin" # default; nil provisions without a role
+end
+```
+
+Set it to `nil` for an app whose review pages are not admin-gated — the account
+is still provisioned (that is what avoids `sign_up_new`), but its role is left
+to the host's own `configure_new_user`.
+
+**The endpoint also answers "who is sitting at this desk?" when the caller names
+nobody.** `?email=` is now optional, and an explicit one still wins. With none,
+the reviewer resolves to `Studio.local_review_email`, and failing that to the
+**first user already holding `Studio.local_review_role`, by id** (that query
+falls back to `"admin"` when the setting is `nil`):
+
+```ruby
+config.local_review_email = "someone@example.com" # nil (default) = derive
+```
+
+This exists so the board's WAITING APPROVAL CTA can be a **public, sign-in-free
+redirect**. Requiring a board session to click it is what broke one-click review
+in the first place; sending an email in that public URL would publish the
+operator's address. The local stack is the machine the reviewer is sitting at,
+so it is the right place to decide. A desk with nobody at that role mints
+nothing and says so, rather than guessing: the derive only ever picks someone
+who ALREADY holds the role, so it never promotes a stranger into it. (The
+`?email=` path does promote the account it is handed — that is the point of it.)
+
+**The floor is unchanged, and now asserted rather than assumed.** The endpoint
+grants a role, so both gates in front of it are tested directly: the
+developer-desk routes are drawn only outside production (proved by drawing
+`Studio.routes` into a throwaway route set under a production env), and a
+non-loopback request 404s **before** provisioning or minting anything.
+Provisioning is best-effort: a host whose `User` rejects the write gets a logged
+warning and a working link, never a 500.
+
+### Added
+
+- **`Studio.local_review_role`** — the role `/_studio/local_review` stamps on the
+  account it provisions before minting. Defaults to `"admin"`; `nil` provisions
+  the account without touching its role.
+- **`Studio.local_review_email`** — who the local-review mint signs in when the
+  caller sends no `?email=`. `nil` (the default) derives the first admin in this
+  database, by id.
+
 ## 0.33.0 — 2026-08-10
 
 Two changes ship together in this release: local log files are now capped, and

data/README.md

@@ -24,6 +24,7 @@ Then `bundle install`. The current release is **v0.6.1**; see [`CHANGELOG.md`](.
 - **Operator tooling**: Shared `studio/banners/environment` banner with Dev Mode + email connector controls, `studio/banners/impersonation`, and an opt-in `Studio::Impersonation` concern for Act As session conventions.
 - **Sluggable concern**: `before_save :set_slug` with `to_param` for human-readable URLs
 - **ThemeSetting model**: Per-app DB overrides with fallback to config defaults
+- **Transactional emails**: `Studio::EmailImage` registry + the shared `/admin/emails` page. Every app inherits the standard emails and their artwork on day one, and can register its own workflows and upload its own banners. See [Transactional emails](#transactional-emails).
 
 ## Configuration
 
@@ -195,6 +196,39 @@ the block:
 <% end %>
 ```
 
+**Page-scoped hosts — `studio/modals/scoped_host`.** When a page must bring its
+own modals (because not every consuming app renders a shared host, and the ones
+that do register their own modal set), render a second host on its own Alpine
+store:
+
+```erb
+<%= render "studio/modals/scoped_host", store: "emailModals" do %>
+  <template x-if="$store.emailModals.current()?.id === 'crop-photo'">
+    <%= render "studio/modals/crop_photo", store: "emailModals" %>
+  </template>
+<% end %>
+```
+
+`studio/modals/_crop_photo` and `_saving` take the same `store:` local, and
+`imageUploadHost({ store: "emailModals", ... })` /
+`submitFormWithProgress(form, { store: "emailModals" })` route through it — all
+default to `"modals"`, so existing call sites are unchanged. The engine's
+`/admin/emails` is the live example.
+
+Two things that will bite you:
+
+- **Render `scoped_host`, not `host`.** This is a non-isolated engine, so an app
+  view at the same path shadows the engine's — and `mcritchie-studio` and
+  `turf-monster` both ship their own `app/views/studio/modals/_host.html.erb`.
+  A page rendering `studio/modals/host` in those apps silently gets the app's
+  fork. `scoped_host` is unforked everywhere.
+- **Guard registrations with `current()?.id`.** The outer template unmounts one
+  tick *after* the stack empties, so a bare `.id` throws on every close.
+
+The scoped host takes its animations from `engine-motion.css` rather than an
+inline copy, so a consumer bundling that layer gets the same spring as the shared
+host.
+
 Store API (`Alpine.store('modals')`):
 
 | Call | Behavior |
@@ -268,6 +302,129 @@ The legacy string locals (`balance_html`, `extra_icons_html`, `div2_html` —
 pre-rendered HTML injected via `raw`) are deprecated but still honored when the
 matching slot is absent, so existing call sites render unchanged.
 
+## Transactional emails
+
+Every consuming app can render the same admin page — **`/admin/emails`** —
+listing each transactional email it sends with the banner riding at the top of
+that email, and whether that banner is the **inherited default** or an
+**app-owned override**. Supersedes the old `/admin/email_images`, which is
+deprecated but still renders for one release.
+
+**The page is opt-in:**
+
+```ruby
+# config/initializers/studio.rb
+config.draw_admin_emails_routes = true
+```
+
+Off by default because `turf-monster` already owns `/admin/emails` and both of
+its helper names; drawing them there raises at route-load and kills every route
+in the app. The gate covers only the page — the registry and the inherited
+defaults are always on.
+
+### The registry
+
+A registered email is mostly symbolic of a workflow — a key, a label, a
+description. The only real asset is its image. The engine pre-registers the two
+every Studio app sends, so a new app inherits both without declaring anything:
+
+| Key | Label |
+|-----|-------|
+| `magic_link` | Magic-link sign-in |
+| `email_change_confirmation` | Email change confirmation |
+
+A host adds its own workflows from an initializer, mirroring
+`Studio::ModelPage.register`:
+
+```ruby
+# config/initializers/studio_emails.rb
+Rails.application.config.to_prepare do
+  Studio::EmailImage.register("winnings", label: "Contest winnings",
+                              description: "Sent when a player wins a contest.")
+  Studio::EmailImage.register("wallet_export", label: "Wallet export")
+end
+```
+
+Re-registering an inherited key updates it in place and keeps its position, so
+relabeling `magic_link` does not reorder the page or drop its default artwork.
+
+### Resolution — inherit, then own
+
+```
+Studio::EmailImage.resolved_url(:magic_link)
+  1. this app's ImageCache row  (its own S3 bucket)   -> app-owned override
+  2. the engine's default gem asset                   -> inherited default
+  3. nil                                              -> sends bannerless
+```
+
+Note the method: **`resolved_url` walks all three layers; `url` returns only
+layer 1** (this app's own image, or nil). That split is deliberate — it keeps
+every caller written before the registry behaving exactly as it did. A mailer
+that already falls back on its own, `url(:magic_link) || own_banner`, must stay
+on `url`; moving it to `resolved_url` makes that fallback unreachable and swaps
+the app's committed artwork for the engine's default.
+
+Defaults **ride the gem** (`app/assets/images/emails/*`), so a brand-new app with
+an empty bucket sends branded email on day one and needs no cross-app S3
+permission. Uploading on an app's `/admin/emails` writes to **that** app's bucket
+and **that** app's `image_caches` row — which is exactly "the asset now belongs
+to this app". Every app has its own bucket and table, so an override never leaks
+between apps.
+
+Three accessors, and picking the wrong one changes what real people receive:
+
+| Call | Returns | Use for |
+|---|---|---|
+| `url(key)` | this app's **own** image, or `nil` | the pre-registry contract; a host doing its own `\|\| fallback` |
+| `resolved_url(key)` | own → inherited default → `nil`, **absolute** | mailers |
+| `preview_url(key)` | own → inherited default (root-relative) | the admin page |
+
+`url` deliberately does **not** resolve to the default. `turf-monster`'s mailer
+reads `Studio::EmailImage.url(:magic_link) || email_banner_url("magic-link-banner.jpg")`
+— making `url` resolve would turn that `||` into dead code and swap its committed
+branded banner for the engine placeholder in live email.
+
+```ruby
+class UserMailer < ApplicationMailer
+  layout "branded_mailer"
+
+  def magic_link(email, token)
+    @banner_url = Studio::EmailImage.resolved_url(:magic_link) # nil renders bannerless
+    # ...
+  end
+end
+```
+
+Do **not** fork `layouts/branded_mailer.html.erb` — the engine's copy is
+app-name-aware through `Studio.app_name`.
+
+### Sharing a bucket — `s3_key_prefix`
+
+Uploads need `Studio.s3_bucket_prefix`. A satellite app that has no bucket of its
+own can share an existing one under its own key namespace:
+
+```ruby
+config.s3_bucket_prefix = "mcritchie-studio"
+config.s3_key_prefix    = "mcritchie-industries/"
+# -> s3://mcritchie-studio-dev/mcritchie-industries/email_banners/...
+```
+
+`Studio::S3` applies the prefix to every operation, so callers keep passing
+logical keys and never see it. Unset (the default) leaves keys byte-identical to
+what every already-shipped app wrote.
+
+An app with **no** bucket configured does not error — `/admin/emails` renders
+read-only, showing the inherited defaults it is genuinely sending and naming the
+one setting that turns uploads on.
+
+### Linking it
+
+Add it to the app's admin sidebar section:
+
+```ruby
+{ label: "Emails", href: admin_emails_path, emoji: "✉️", desc: "Transactional email banners" }
+```
+
 ## Overriding Views
 
 This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.

data/app/controllers/studio/email_images_controller.rb

@@ -1,7 +1,22 @@
 module Studio
-  # Admin page to manage the banner image on transactional emails (Studio::
-  # EmailImage). One managed variant today (magic_link); the registry is the
-  # extension point. Shared by every app — surfaced from each app's admin hub.
+  # DEPRECATED — superseded by Studio::EmailsController (/admin/emails), which
+  # shows every registered email with its live image, says whether that image is
+  # the inherited default or app-owned, and uploads through the crop modal.
+  #
+  # Kept alive for ONE release on purpose, not by neglect. consumer-ci.yml checks
+  # out each consumer repo with no `ref:` — i.e. its DEFAULT BRANCH — and runs
+  # that suite against the engine PR. mcritchie-studio and turf-monster both have
+  # tests on `main` that drive this page and its admin_email_image_path helper,
+  # so deleting it here would redden their lanes from the moment the PR opens,
+  # and nothing inside the engine PR could fix it: the consumer PRs would have to
+  # travel accepted -> release -> main in BOTH apps before this could go green.
+  #
+  # So the retirement is staged: this release adds /admin/emails and leaves this
+  # page working; each app's adoption task moves its link and its tests; a later
+  # engine minor deletes this file, its view, and its two routes once no
+  # consumer's main references them.
+  #
+  # It is not frozen in its broken state, though — see #index.
   class EmailImagesController < ApplicationController
     before_action :require_admin
 
@@ -11,6 +26,26 @@ module Studio
       @variants = Studio::EmailImage.variants
     end
 
+    # The canonical page this one is being retired in favour of, or nil when this
+    # app has not drawn it. Rendered as a banner at the top of the old view so an
+    # admin who lands here by a stale link is walked forward.
+    #
+    # The nil case is REAL, not defensive padding: /admin/emails is opt-in
+    # (Studio.draw_admin_emails_routes, default off because turf-monster owns the
+    # name), so on any app that has not opted in the helper does not exist and a
+    # bare call raises NameError — which 500s this page. Consumer CI caught
+    # exactly that on mcritchie-studio.
+    #
+    # Asks the ROUTER rather than the config flag: the flag is read at route-draw
+    # time, so a host that flips it afterwards would still have no route, and the
+    # router is the thing that actually knows.
+    def successor_path
+      return nil unless Rails.application.routes.named_routes.key?(:admin_emails)
+
+      admin_emails_path
+    end
+    helper_method :successor_path
+
     # PATCH /admin/email_images/:variant — upload/replace a banner.
     def update
       variant = params[:variant].to_s

data/app/controllers/studio/emails_controller.rb

@@ -0,0 +1,85 @@
+module Studio
+  # /admin/emails — the standard transactional-email page every Studio app gets,
+  # modelled on the living style guide (/admin/style): a plain host-inherited
+  # controller whose view is a bare content wrapper, so it renders inside each
+  # host's application layout and picks up that app's navbar and theme.
+  #
+  # It lists Studio::EmailImage's registry — one row per registered email, each
+  # showing its live banner and whether that banner is the INHERITED engine
+  # default or an APP-OWNED override — and writes an override through the shared
+  # crop modal. Replaces /admin/email_images, which now redirects here.
+  #
+  # An app whose host never set Studio.s3_bucket_prefix cannot store an override.
+  # That is a read-only page, not an error: uploads_available? gates the write
+  # actions and the view explains why, so the page still shows what each email
+  # is currently sending.
+  class EmailsController < ApplicationController
+    before_action :require_admin
+    before_action :load_entry, only: %i[update destroy]
+    before_action :require_uploads, only: %i[update destroy]
+
+    MAX_BYTES = 8.megabytes
+
+    def index
+      @entries = Studio::EmailImage.entries
+      @uploads_available = Studio::EmailImage.uploads_available?
+    end
+
+    # PATCH /admin/emails/:key — upload/replace this app's own banner.
+    def update
+      file = params[:image]
+      unless valid_image?(file)
+        message = file.blank? ? "Choose an image to upload." : "Use a PNG, JPG, or WebP under 8 MB."
+        return redirect_to admin_emails_path, alert: message, status: :see_other
+      end
+
+      rescue_and_log do
+        Studio::EmailImage.store(@key, io: file, content_type: file.content_type)
+        redirect_to admin_emails_path, notice: "#{Studio::EmailImage.label(@key)} banner updated.", status: :see_other
+      end
+    rescue StandardError
+      redirect_to admin_emails_path, alert: "Couldn't save the image. Please try again.", status: :see_other
+    end
+
+    # DELETE /admin/emails/:key — drop this app's override and fall back to the
+    # inherited default.
+    def destroy
+      # rescue_and_log, like #update: destroy is a WRITE path (it drops an
+      # ImageCache row and deletes the S3 object behind it), and the bare rescue
+      # below turns any failure into a friendly alert. Without the log that
+      # failure is invisible — the admin sees "try again" and nothing reaches
+      # ErrorLog to say why.
+      rescue_and_log do
+        reverted = Studio::EmailImage.revert(@key)
+        notice = if reverted
+                   "#{Studio::EmailImage.label(@key)} reverted to the inherited default."
+                 else
+                   "#{Studio::EmailImage.label(@key)} was already using the inherited default."
+                 end
+        redirect_to admin_emails_path, notice: notice, status: :see_other
+      end
+    rescue StandardError
+      redirect_to admin_emails_path, alert: "Couldn't revert the image. Please try again.", status: :see_other
+    end
+
+    private
+
+    def load_entry
+      @key = params[:key].to_s
+      head :not_found unless Studio::EmailImage.known?(@key)
+    end
+
+    def require_uploads
+      return if Studio::EmailImage.uploads_available?
+
+      redirect_to admin_emails_path, status: :see_other,
+                  alert: "This app has no object storage configured, so email images can't be changed here yet."
+    end
+
+    def valid_image?(file)
+      file.respond_to?(:content_type) &&
+        file.content_type.to_s.start_with?("image/") &&
+        file.respond_to?(:size) && file.size.to_i.positive? && file.size <= MAX_BYTES
+    end
+  end
+end

data/app/controllers/studio/local_reviews_controller.rb

@@ -19,6 +19,15 @@ module Studio
   # exposure the inbox already carries, which hands every captured sign-in link
   # to any local reader. It is a development desk convenience; it is not a
   # sign-in path.
+  #
+  # It also PROVISIONS the account before minting, at Studio.local_review_role
+  # (default "admin"). The email the board hands over is the operator's
+  # PRODUCTION address, and a fresh worktree database has never seen it — so
+  # without this the consume takes Studio::LinkConsumption#sign_up_new, creates
+  # him at the default role ("viewer"), and `require_admin` on the page under
+  # review redirects him to "/". The sign-in SUCCEEDS and he never sees the
+  # page, which is what made the failure so quiet: a seeded admin works, so only
+  # the operator's real address ever hit it.
   class LocalReviewsController < ApplicationController
     include Studio::MagicLinkIssuing
 
@@ -27,9 +36,13 @@ module Studio
     before_action :require_local_development!
 
     def show
-      email = Studio::LinkToken.normalize_email(params[:email])
+      email = reviewer_email
       return redirect_to(login_path, alert: MISSING_EMAIL) unless email.match?(URI::MailTo::EMAIL_REGEXP)
 
+      # Provision BEFORE minting, so the consume finds an existing account and
+      # takes sign_in_existing rather than sign_up_new-at-the-default-role.
+      provision_reviewer(email)
+
       # return_to is passed through raw: the store sanitizes it to a same-origin
       # path on the way in (Studio::Link.create_magic_link calls
       # Studio::LinkToken.sanitize_path). Re-sanitizing here would be a second
@@ -43,6 +56,77 @@ module Studio
 
     MISSING_EMAIL = "Add ?email=<your address> to mint a local review link."
 
+    # WHO to sign in, in priority order:
+    #
+    #   1. `?email=` — an explicit caller still wins.
+    #   2. `Studio.local_review_email` — the app's declared desk operator.
+    #   3. the first admin in this database — the seeded operator, by id.
+    #
+    # The board deliberately stops at (1) being ABSENT. Its WAITING APPROVAL CTA
+    # is a public, sign-in-free redirect, so an email in that URL would be an
+    # address published on a public page for anyone to read. The local stack is
+    # the right place to answer "who is at this desk": it is the machine the
+    # reviewer is sitting at, and it already knows its own operator.
+    def reviewer_email
+      Studio::LinkToken.normalize_email(
+        params[:email].presence || Studio.local_review_email.presence || seeded_admin_email
+      )
+    end
+
+    # The database's own first admin. Ordered by id so a re-seeded desk resolves
+    # to the same person every time rather than to whoever was touched last.
+    # Rescued because this runs before the mint on every click: a host with no
+    # role column must fall through to MISSING_EMAIL, not a 500.
+    def seeded_admin_email
+      return nil unless User.respond_to?(:column_names) && User.column_names.include?("role")
+
+      User.where(role: Studio.local_review_role.presence || "admin").order(:id).first&.email
+    rescue StandardError => e
+      Rails.logger.warn("[Studio::LocalReviewsController] no default reviewer: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # Find-or-create the reviewer and ensure Studio.local_review_role, so the
+    # page under review actually RENDERS for whoever follows the link.
+    #
+    # Best-effort by design. Provisioning is an upgrade to the mint, not a
+    # precondition of it: a host with an extra User validation must not turn the
+    # review button into a 500 — it should still hand back a working sign-in
+    # link, exactly as it did before this method existed. So a failure is logged
+    # loudly and the mint proceeds. The end-to-end check that the operator
+    # actually lands ON the page is the real gate; this is the thing that makes
+    # it pass, not the thing that proves it.
+    # `User` is referenced bare, with no defined?/const_defined? guard: those do
+    # not agree with each other about a Zeitwerk autoload that has not fired
+    # yet, and a guard that reads "absent" on a cold boot would skip
+    # provisioning silently — the failure mode being fixed. Studio::LinkConsumption
+    # already requires every consuming app to have User, so a genuinely missing
+    # one is a NameError the rescue below logs like any other host mismatch.
+    def provision_reviewer(email)
+      user = User.find_by(email: email) || build_reviewer(email)
+      role = Studio.local_review_role.presence
+      user.role = role if role && user.respond_to?(:role=) && user.role != role
+      user.save! if user.new_record? || user.changed?
+      user
+    rescue StandardError => e
+      # No re-raise: see "best-effort" above. Logged at warn because a silent
+      # miss here reappears as the exact symptom this endpoint exists to remove
+      # — a successful sign-in that lands on the wrong page.
+      Rails.logger.warn(
+        "[Studio::LocalReviewsController] could not provision #{email}: #{e.class}: #{e.message}"
+      )
+      nil
+    end
+
+    # A brand-new reviewer goes through the host's own new-user hook first, so
+    # the account this endpoint creates is shaped like every other account in
+    # the app (usernames, defaults, associations) — then the role is stamped on
+    # top. Mirrors Studio::LinkConsumption#sign_up_new, which is the path this
+    # provisioning is standing in for.
+    def build_reviewer(email)
+      User.new(email: email).tap { |user| Studio.configure_new_user.call(user) }
+    end
+
     def require_local_development!
       head :not_found unless Studio.local_tool_enabled?(request_local: request.local?)
     end