seams 0.1.0

data/lib/generators/seams/admin/templates/README.md.tt

@@ -0,0 +1,266 @@
+# Seams Admin
+
+> Mountable admin engine for a Seams-powered host. Built on
+> [Administrate](https://github.com/thoughtbot/administrate) for the
+> dashboard surface and [Pundit](https://github.com/varvet/pundit) for
+> per-record authorisation. Read-only over the existing seams tables —
+> ships no migrations of its own.
+
+## 30-second elevator pitch
+
+`bin/rails generate seams:admin` writes an `engines/admin/` engine into
+your host that mounts at `/admin` and ships:
+
+- Twelve Administrate dashboards covering the canonical seams models
+  (Identity, Account, Membership × 2, Team, TeamMembership, Invitation,
+  Notification, NotificationPreference, Plan, Subscription, Invoice,
+  LifetimePass).
+- Two operating modes — **platform** (admins see everything) and
+  **tenant** (admins are scoped to their own Account) — selected by a
+  single config knob.
+- Pundit policies under `Admin::Platform::*` and `Admin::Tenant::*`,
+  selected at request time by `Seams::Admin.config.tenancy_scope`.
+- Audit-log auto-write — every successful create/update/destroy emits a
+  `Core::AuditLog` row keyed on `Auth::Current.identity`.
+- Four config knobs (`authenticator`, `tenancy_scope`, `theme_css_path`,
+  `before_admin_action`) for the predictable customisation surface.
+
+No migrations, no new tables, no admin-only User model — see
+"[Why `staff?` on Identity, not a separate `AdminUser` table?](#why-staff-on-identity-not-a-separate-adminuser-table)"
+below.
+
+## First sign-in (do this first)
+
+After `bundle install` picks up `administrate` + `pundit`, promote
+yourself to a platform admin from the Rails console (or via runner):
+
+```ruby
+Auth::Identity.find_by(email: "you@example.com").update!(staff: true)
+```
+
+Then boot the host and visit `/admin`:
+
+```bash
+bin/rails server
+open http://localhost:3000/admin
+```
+
+You should land on the Identities index with sidebar entries for all
+twelve canonical models. If you see "Access denied" instead, the
+authenticator returned a falsey value — double-check `staff` is set on
+your Identity row (`Auth::Identity.find_by(email: ...).staff?` should
+return `true`).
+
+## Two-mode operation
+
+The admin surface supports two tenancy modes, switched via a single
+config knob:
+
+### `:platform` mode (default)
+
+```ruby
+# config/initializers/seams_admin.rb
+Seams::Admin.configure { |c| c.tenancy_scope = :platform }
+```
+
+- **Gate:** `Auth::Identity#staff?` (boolean column on
+  `auth_identities`).
+- **Visibility:** every Account's data, unfiltered.
+- **Use case:** internal operator console — support staff
+  impersonation, cross-account search, billing reconciliation.
+- **Policies:** `Admin::Platform::*Policy` namespace.
+
+### `:tenant` mode
+
+```ruby
+# config/initializers/seams_admin.rb
+Seams::Admin.configure { |c| c.tenancy_scope = :tenant }
+```
+
+- **Gate:** `Accounts::Membership#role == "admin"` (read off
+  `Accounts::Current.membership`).
+- **Visibility:** only the current Account's data — every Pundit
+  `Scope` filters by `account_id`.
+- **Use case:** a tenant-facing admin surface where each customer's
+  admin sees their own users / invoices / teams only.
+- **Policies:** `Admin::Tenant::*Policy` namespace.
+- **Requires:** the `accounts` engine. Without it the admin engine
+  fails fast at boot with a clear error message.
+
+Switching modes is a config flip — no schema change, no regenerate.
+The `policy_namespace` lookup on `Seams::Admin::ApplicationController`
+reads `Seams::Admin.config.tenancy_scope` on every request.
+
+## Configuration
+
+Four knobs, deliberately small:
+
+```ruby
+# config/initializers/seams_admin.rb
+Seams::Admin.configure do |c|
+  # 1. authenticator — Callable taking the controller, returning truthy
+  # when the request is allowed in. Default: ->(ctrl) { ctrl.current_identity&.staff? }
+  c.authenticator = ->(ctrl) { ctrl.current_identity&.staff? }
+
+  # 2. tenancy_scope — :platform | :tenant. Selects the policy namespace
+  # at request time. See "Two-mode operation" above.
+  c.tenancy_scope = :platform
+
+  # 3. theme_css_path — Optional path to a host-supplied CSS file loaded
+  # on top of Administrate's stock styling. nil = use Administrate's
+  # defaults.
+  c.theme_css_path = nil
+
+  # 4. before_admin_action — Optional callable that runs before every
+  # admin action. The recommended hook for 2FA enforcement, IP
+  # allow-listing, audit-trail entry-point logging, etc. Receives the
+  # controller; raise to halt the request.
+  c.before_admin_action = nil
+end
+```
+
+Follow-up generators that ship new knobs splice their `attr_accessor`
+into the `admin.configuration.attributes` insertion point in
+`engines/admin/lib/admin/configuration.rb` and the matching default
+into `admin.configuration.defaults`.
+
+## Why `staff?` on Identity, not a separate `AdminUser` table?
+
+Classic Rails apps separate `User` and `AdminUser` because `User`
+carries customer-facing concerns (orders, billing, notifications, etc.)
+that you do not want admins to inherit. **In seams Wave 9
+`Auth::Identity` is *already* the credential-only object** — it has no
+customer concerns to inherit from. Customer-facing data lives on
+`Accounts::Membership` (account-scoped) and the host's own domain
+models. A boolean `staff?` flag on Identity is the right granularity.
+
+The seams "User and AdminUser must live on separate tables" rule is
+**reinterpreted, not violated**: the rule's intent (no customer state
+on the admin authentication object) is fully satisfied by the Wave 9
+credential-only Identity. Flagging it explicitly here so future
+contributors don't read this engine and assume the rule was forgotten.
+
+Hosts that need hard isolation (regulatory compliance, separate auth
+flow, dedicated SSO for admins) override the authenticator:
+
+```ruby
+Seams::Admin.configure do |c|
+  c.authenticator = ->(ctrl) { ctrl.current_admin_user.present? }
+end
+```
+
+…and bring their own `current_admin_user` resolution from a separate
+auth surface.
+
+## Customising a dashboard (Ejecting)
+
+The seams pattern: **eject the dashboard, then edit your local copy**.
+Future `bin/seams admin` runs leave ejected files alone.
+
+```bash
+bin/seams resolve --eject admin/app/dashboards/admin/identity_dashboard.rb
+# Now edit engines/admin/app/dashboards/admin/identity_dashboard.rb freely.
+```
+
+For new dashboards covering host-specific models, generate via
+Administrate, then move the result under the `Admin::*` namespace:
+
+```bash
+bin/rails generate administrate:dashboard MyHost::Project
+# Move app/dashboards/my_host/project_dashboard.rb to
+# engines/admin/app/dashboards/admin/project_dashboard.rb
+# Move the controller similarly under app/controllers/admin/.
+# Add `resources :projects, controller: "admin/projects"` to
+# engines/admin/config/routes.rb (or splice via the
+# admin.routes.after_resources insertion point in a follow-up generator).
+```
+
+Administrate's full dashboard / field / controller surface is documented
+at <https://administrate-demo.herokuapp.com/>.
+
+## Error messages a host operator will see
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `[seams admin] missing required dependency: Auth::Identity ...` at boot | The auth engine isn't installed. | `bin/rails generate seams:auth` |
+| `[seams admin] missing required dependency: Administrate ...` at boot | `gem "administrate"` not in the host Gemfile. | `bundle install` (the admin generator wires it; if you regenerated and skipped, add `gem "administrate", "~> 1.0"` manually). |
+| `[seams admin] missing required dependency: Pundit ...` at boot | `gem "pundit"` not in the host Gemfile. | Same fix — the generator wires it. |
+| 403 "Access denied. The seams admin surface is gated on `Seams::Admin.config.authenticator`..." on every request | The configured gate returned falsey for the signed-in Identity. | Default gate is `current_identity&.staff?`. Set `staff: true` on your Identity row, or override the authenticator. |
+| `Pundit::NotAuthorizedError` mid-request | A per-action policy denied the request. | Eject the relevant policy under `engines/admin/app/policies/admin/{platform,tenant}/<resource>_policy.rb` and override the action predicate (e.g. `def destroy?; false; end`). |
+
+## What's not shipped (deferred)
+
+- **2FA / IP allow-list for `/admin`.** Not shipped. Wire your own via
+  `Seams::Admin.config.before_admin_action`.
+- **Branded UI.** Stock Administrate CSS only in v1. Override via
+  `theme_css_path`.
+- **Search beyond Administrate's stock.** Administrate ships a basic
+  Ransack-backed search; rich filtering / faceted search is your job.
+- **Batch actions.** Not in Administrate's surface; not shipped here.
+  Override the relevant controller's `index` action and emit your own
+  bulk-action button if you need them.
+
+## Insertion-point markers
+
+This engine ships five Wave-10 insertion-point markers that follow-up
+generators target:
+
+| Marker | File | Purpose |
+| --- | --- | --- |
+| `admin.engine.events` | `lib/admin/engine.rb` | Register new admin events (e.g. `admin.action.taken.admin`). |
+| `admin.routes.before_resources` | `config/routes.rb` | Ahead-of-resource routes (impersonation entry points, bulk-action endpoints). |
+| `admin.routes.after_resources` | `config/routes.rb` | New top-level admin routes (custom collection routes, JSON-only endpoints). |
+| `admin.configuration.attributes` | `lib/admin/configuration.rb` | New configuration knobs. |
+| `admin.configuration.defaults` | `lib/admin/configuration.rb` | Defaults for the new knobs. |
+
+`bin/seams resolve --list-markers admin` prints the live list against
+the engine source.
+
+## Audit log
+
+Every successful create/update/destroy on an admin dashboard writes a
+`Core::AuditLog` row via the `record_admin_audit` after_action. The
+row carries:
+
+- `action` — `"create"`, `"update"`, or `"destroy"`.
+- `auditable_type` / `auditable_id` — the resource Administrate
+  resolved.
+- `actor_id` — `Auth::Current.identity&.id`.
+- `payload` — for updates, `record.saved_changes.transform_values(&:last)`;
+  for create/destroy, attributes minus timestamps.
+
+If the core engine isn't installed (and `Core::AuditLog` is therefore
+undefined), the after_action no-ops cleanly — admin still works,
+audit log is silently absent.
+
+## Why Administrate?
+
+Considered: ActiveAdmin, Avo, Trestle, Motor Admin, RailsAdmin, and
+hand-rolling on top of Rails 8 scaffolds. Administrate wins because:
+
+- Dashboards are plain Ruby classes (`Admin::IdentityDashboard <
+  Administrate::BaseDashboard`). No DSL, no Arbre. Matches seams' house
+  style.
+- Custom fields are `rails g administrate:field foo` — a class + an ERB
+  partial. Perfect for masking encrypted columns and rendering Stripe
+  IDs.
+- ORM-agnostic.
+- Pundit-aware via documented `policy_namespace` integration. Clean
+  surface for the platform-vs-tenant policy split.
+- thoughtbot maintains it.
+- Easiest of the surveyed frameworks to embed inside another engine —
+  no assumption that the host owns `/admin`.
+
+The full per-framework comparison lives in
+`proposals/admin_engine_administrate.md` (the Wave 11A research
+report).
+
+## Running the specs
+
+```bash
+bin/rails seams:test[admin]
+```
+
+The boot spec asserts the engine loads, the four config knobs default
+correctly, every dashboard + policy class is reachable, and both
+tenancy modes route to the right policy namespace.

data/lib/generators/seams/admin/templates/app/controllers/admin/accounts_controller.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Administrate controller for the Accounts::Account dashboard.
+# Subclasses Seams::Admin::ApplicationController so the gate, the
+# pundit_user hook, and Phase 3's audit-log auto-write apply.
+module Admin
+  class AccountsController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Accounts::Account
+    end
+
+    def dashboard
+      @dashboard ||= AccountDashboard.new
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/accounts_memberships_controller.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Administrate controller for the Accounts::Membership dashboard.
+# Routed under `accounts_memberships` (engine-prefixed) to disambiguate
+# from `teams_memberships` — both engines ship a Membership model.
+module Admin
+  class AccountsMembershipsController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Accounts::Membership
+    end
+
+    def dashboard
+      @dashboard ||= AccountsMembershipDashboard.new
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/application_controller.rb.tt

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Seams
+  module Admin
+    # Base controller for the seams admin engine. Subclasses
+    # Administrate::ApplicationController so dashboards (Phase 2) get
+    # the framework's defaults — index/show/new/create/edit/update/destroy,
+    # search, filtering, pagination — for free.
+    #
+    # ## Three layered responsibilities
+    #
+    # 1. **Authentication gate** — Phase 1's `Seams::Admin::Authenticator`
+    #    concern installs `before_action :authenticate_admin!`. Default
+    #    gate: `current_identity&.staff?`. Configurable via
+    #    `Seams::Admin.config.authenticator`.
+    #
+    # 2. **Resource-level authorisation** — Phase 3 wires Pundit via
+    #    Administrate's canonical `Administrate::Punditize` concern.
+    #    `Punditize` is the integration thoughtbot ships and documents:
+    #    it overrides Administrate's `authorized_action?` and
+    #    `scoped_resource` to delegate to Pundit, so a per-action
+    #    permission check (`policy.update?`) AND the list-view
+    #    `policy_scope` both fire automatically. Without including
+    #    `Punditize`, Administrate's default `authorized_action?`
+    #    returns true for everything — Pundit policies would be loaded
+    #    but never consulted.
+    #
+    #    The platform-vs-tenant split lives in `policy_namespace`:
+    #    Pundit's array-form lookup (`Pundit.policy!(user, [ns, record])`)
+    #    resolves to `Admin::Platform::*Policy` or
+    #    `Admin::Tenant::*Policy` depending on the active mode.
+    #
+    # 3. **Audit-log auto-write** — Phase 3 emits a `Core::AuditLog` row
+    #    for every successful create/update/destroy via the
+    #    `record_admin_audit` after_action. The actor is
+    #    `Auth::Current.identity` (the human driving the request); the
+    #    auditable is Administrate's `requested_resource`.
+    #
+    # The order here is deliberate: gate, then authorise, then act,
+    # then audit. A request that fails the gate never reaches a
+    # policy; a request that fails a policy never reaches the action;
+    # the audit row only writes after a successful action.
+    class ApplicationController < ::Administrate::ApplicationController
+      include ::Seams::Admin::Authenticator
+      # Administrate's canonical Pundit integration. Internally:
+      #   - includes Pundit::Authorization
+      #   - overrides `authorized_action?` to call
+      #     `Pundit.policy!(pundit_user, [*policy_namespace, resource]).public_send("#{action}?")`
+      #   - overrides `scoped_resource` to apply `Pundit.policy_scope!`
+      #     using the same array-form namespace
+      #   - overrides `authorize_resource` to use `authorize` with the
+      #     namespaced array
+      # Defining our own `policy_namespace` is the supported way to
+      # switch between Admin::Platform::* and Admin::Tenant::*.
+      include ::Administrate::Punditize
+
+      # Pundit raises `Pundit::NotAuthorizedError` when a policy denies a
+      # request. Without an explicit rescue the host inherits the
+      # exception and renders a 500. Treat it as a 403 and surface a
+      # clear message; the after_action audit hook also runs (response
+      # is set), so audit_log records the rejected attempt.
+      rescue_from ::Pundit::NotAuthorizedError, with: :respond_with_admin_unauthorised
+
+      # Catch the parallel exception Administrate raises from inside its
+      # own `authorize_resource` when (for whatever reason) Punditize is
+      # bypassed. Same handling — present the operator with a 403.
+      rescue_from ::Administrate::NotAuthorizedError, with: :respond_with_admin_unauthorised
+
+      # Phase 3 audit-log auto-write. Runs after successful create /
+      # update / destroy actions. Wrapped in `if defined?(Core::AuditLog)`
+      # so the engine is usable without the seams core engine —
+      # operators who don't ship core get no audit log, which is the
+      # correct behaviour when the table doesn't exist.
+      after_action :record_admin_audit, only: %i[create update destroy]
+
+      # Pundit ships `verify_authorized` / `verify_policy_scoped`
+      # after_actions that raise if a controller didn't call
+      # `authorize` / `policy_scope`. Administrate's `Punditize`
+      # already calls them on every standard action, so any future
+      # custom action added to a subclass that forgets the call gets
+      # caught loudly in development. `:only` excludes `:index`
+      # (covered by `verify_policy_scoped` instead) and the rescue
+      # responders themselves (which never authorise — they 403).
+      after_action :verify_authorized,    except: %i[index respond_with_admin_unauthorised]
+      after_action :verify_policy_scoped, only:   %i[index]
+
+      # Helper exposed to dashboards so they can read the active
+      # tenancy mode (:platform vs :tenant). Phase 3 reads this in
+      # policy scopes; dashboards may also branch on it for
+      # account_id columns.
+      helper_method :seams_admin_tenancy_scope
+
+      def seams_admin_tenancy_scope
+        ::Seams::Admin.config.tenancy_scope
+      end
+
+      # Pundit hook. Returns a `Seams::Admin::Context` Struct wrapping
+      # the current Identity and the current Accounts::Membership so
+      # tenant policies can read both signals (staff? + role/account_id)
+      # without each policy reaching into the controller. Returning a
+      # raw Identity would lose the membership; returning the
+      # controller would expose too much. The Struct is the smallest
+      # surface that lets every policy stay decoupled from request
+      # state.
+      #
+      # `current_membership` is read defensively: hosts that don't
+      # ship the accounts engine (platform-only deployments) leave it
+      # nil, and the platform policies don't need it.
+      def pundit_user
+        identity   = ::Auth::Current.identity if defined?(::Auth::Current)
+        membership = current_membership_for_admin
+        ::Seams::Admin::Context.new(identity, membership)
+      end
+
+      # The Pundit policy namespace for the active tenancy mode.
+      # `Administrate::Punditize` calls `Pundit.policy!(pundit_user,
+      # [*policy_namespace, resource])` — Pundit's array-form lookup
+      # walks the namespace tree (`Admin::Platform::IdentityPolicy`
+      # for an `Auth::Identity` resource under `[Admin, Platform]`).
+      # Returning an Array of constants (NOT a single Module) is what
+      # Punditize expects.
+      #
+      # The `Admin` segment is the engine's policy module root; the
+      # second segment switches on tenancy mode. Hosts switching modes
+      # at runtime per-request (rare; typically configured once at boot)
+      # override this method on a subclass and consult their own request
+      # state.
+      def policy_namespace
+        case ::Seams::Admin.config.tenancy_scope
+        when :tenant   then [::Admin::Tenant]
+        else                [::Admin::Platform]
+        end
+      end
+
+      private
+
+      # Resolve the current Accounts::Membership for tenant-mode
+      # policy decisions. Delegates to
+      # `Seams::Admin.config.current_membership_resolver` (a callable
+      # taking the controller). The default reads
+      # `Accounts::Current.membership` (Wave 9's CurrentAttributes
+      # object). Hosts using a different membership-resolution shape
+      # set their own resolver in `config/initializers/seams_admin.rb`
+      # rather than ejecting this controller.
+      def current_membership_for_admin
+        resolver = ::Seams::Admin.config.current_membership_resolver
+        return nil unless resolver.respond_to?(:call)
+
+        resolver.call(self)
+      rescue StandardError => e
+        Rails.logger.warn("[seams admin] membership resolver raised: #{e.class}: #{e.message}") if defined?(Rails)
+        nil
+      end
+
+      # Phase 3 audit-log auto-write. Records a `Core::AuditLog` row
+      # for every successful create/update/destroy.
+      #
+      # Three guards keep the row from writing in cases that would
+      # either crash or duplicate:
+      #
+      #   - `defined?(::Core::AuditLog)` — the engine is usable
+      #     without the seams core engine; no constant means no row.
+      #   - `response.successful? || response.redirect?` — only audit
+      #     actions whose response is in the 2xx/3xx range. A failed
+      #     update (4xx) skipped through the after_action shouldn't
+      #     leave a misleading "update happened" row.
+      #   - `record.respond_to?(:audit_logs)` — when the host model
+      #     already includes `Core::Auditable`, that concern's
+      #     `after_commit` hook ALREADY wrote a row. Writing a second
+      #     row from this controller would double-log. We detect the
+      #     `audit_logs` association the concern installs and skip.
+      #
+      # `requested_resource` is Administrate's resolved record. On
+      # `create` it's the just-saved record; on `update` it's the
+      # just-updated record; on `destroy` it's the record that was just
+      # destroyed (frozen but still readable for `id` / `class.name`).
+      def record_admin_audit
+        return unless defined?(::Core::AuditLog)
+        return unless response.successful? || response.redirect?
+
+        record = requested_resource_for_audit
+        return if record.nil?
+        return if auditable_via_concern?(record)
+
+        ::Core::AuditLog.create!(
+          action:         action_name,
+          auditable_type: record.class.name,
+          auditable_id:   record.id,
+          actor_id:       admin_audit_actor_id,
+          payload:        admin_audit_payload(record)
+        )
+      rescue StandardError => e
+        # Audit-log failures must not break the admin response. A
+        # missing column, a transient DB hiccup, or a unique-constraint
+        # violation should be logged and swallowed — the admin action
+        # itself already succeeded by the time after_action runs.
+        # Operators wanting a structured signal can subscribe to
+        # ActiveSupport::Notifications "seams.admin.audit_failed".
+        Rails.logger.warn("[seams admin] audit log write failed: #{e.class}: #{e.message}") if defined?(Rails)
+        if defined?(::ActiveSupport::Notifications)
+          ::ActiveSupport::Notifications.instrument(
+            "seams.admin.audit_failed",
+            error_class: e.class.name, message: e.message,
+            action: action_name, resource_class: record&.class&.name
+          )
+        end
+      end
+
+      # Read `requested_resource` defensively. On a destroy action
+      # Administrate's `requested_resource` is the just-destroyed
+      # (frozen) record; reading `.id` and `.class.name` still works.
+      # On other actions Administrate caches the resource in
+      # `@requested_resource`, so calling the public method is cheap.
+      # Wrap in a rescue: if the action never resolved a resource (a
+      # subclass that overrode `requested_resource` to raise) we don't
+      # want the audit hook to take down the whole response.
+      def requested_resource_for_audit
+        respond_to?(:requested_resource, true) ? requested_resource : nil
+      rescue StandardError
+        nil
+      end
+
+      # `Core::Auditable` adds `has_many :audit_logs` to the host model
+      # AND wires `after_commit` callbacks that write a row directly.
+      # If the model includes the concern, the row was already written
+      # by the model's own callback — writing another from here would
+      # double-log. The `audit_logs` association is the cheapest
+      # detection signal that doesn't require requiring `Core::Auditable`
+      # itself (which lives in the core engine, not loaded by the
+      # admin engine's dummy app).
+      def auditable_via_concern?(record)
+        return false unless record.class.respond_to?(:reflect_on_association)
+
+        reflection = record.class.reflect_on_association(:audit_logs)
+        return false if reflection.nil?
+
+        reflection.options[:as] == :auditable
+      end
+
+      def admin_audit_actor_id
+        return nil unless defined?(::Auth::Current)
+
+        ::Auth::Current.identity&.id
+      end
+
+      def admin_audit_payload(record)
+        case action_name
+        when "update"
+          # `saved_changes` is the canonical Rails surface for "what
+          # this update actually wrote", available on the just-saved
+          # record. Empty for a no-op update.
+          record.respond_to?(:saved_changes) ? record.saved_changes.transform_values(&:last) : {}
+        else
+          # create + destroy snapshot the attributes minus timestamps
+          # so the row is readable without the audit-log consumer
+          # having to filter timestamp noise.
+          record.respond_to?(:attributes) ? record.attributes.except("created_at", "updated_at") : {}
+        end
+      end
+
+      # Pundit / Administrate authorisation failure handler. Renders a
+      # plain 403 — same shape as the authenticator concern's
+      # `respond_with_admin_forbidden` to keep the operator-visible
+      # surface consistent.
+      def respond_with_admin_unauthorised(_exception = nil)
+        message = <<~MSG.strip
+          Access denied. The seams admin engine's Pundit policy denied
+          this request. The active tenancy mode is
+          `Seams::Admin.config.tenancy_scope = #{::Seams::Admin.config.tenancy_scope.inspect}`;
+          if you expected access, check the matching policy under
+          `Admin::#{::Seams::Admin.config.tenancy_scope.to_s.camelize}::*Policy`.
+        MSG
+
+        if respond_to?(:render)
+          render plain: message, status: :forbidden
+        else
+          head :forbidden
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/identities_controller.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Administrate controller for the Auth::Identity dashboard.
+#
+# Subclasses Seams::Admin::ApplicationController (Phase 1's
+# gate-bearing parent) so the authenticator concern, the
+# `pundit_user` hook, and Phase 3's audit-log auto-write apply
+# uniformly across every dashboard. Do NOT inherit directly from
+# Administrate::ApplicationController — that bypasses the gate.
+#
+# Administrate resolves `resource_class` from the controller name
+# automatically via its inflector hook, but we override it explicitly
+# here because the Identity model lives under the Auth namespace
+# (Auth::Identity) and the default inflection would resolve to a
+# top-level Identity constant that does not exist.
+module Admin
+  class IdentitiesController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Auth::Identity
+    end
+
+    def dashboard
+      @dashboard ||= IdentityDashboard.new
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/invitations_controller.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Administrate controller for the Teams::Invitation dashboard.
+module Admin
+  class InvitationsController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Teams::Invitation
+    end
+
+    def dashboard
+      @dashboard ||= InvitationDashboard.new
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/invoices_controller.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Administrate controller for the Billing::Invoice dashboard.
+module Admin
+  class InvoicesController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Billing::Invoice
+    end
+
+    def dashboard
+      @dashboard ||= InvoiceDashboard.new
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/lifetime_passes_controller.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Administrate controller for the Billing::LifetimePass dashboard.
+module Admin
+  class LifetimePassesController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Billing::LifetimePass
+    end
+
+    def dashboard
+      @dashboard ||= LifetimePassDashboard.new
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/controllers/admin/notification_preferences_controller.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Administrate controller for the
+# Notifications::NotificationPreference dashboard.
+module Admin
+  class NotificationPreferencesController < ::Seams::Admin::ApplicationController
+    def resource_class
+      ::Notifications::NotificationPreference
+    end
+
+    def dashboard
+      @dashboard ||= NotificationPreferenceDashboard.new
+    end
+  end
+end