protege 0.1.0.alpha.1

data/db/migrate/20260706120130_create_protege_traces.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Create the protege_traces table — an opt-in, durable snapshot of every inference turn kept for later
+# fine-tuning. Deliberately standalone and minimal: no foreign keys, no references, and no identity
+# columns (persona/provider). A trace records only what affects training — the +request+ as sent, the
+# +response+ it produced, and the inference settings (+model+ + +settings+) that shaped it — plus a
+# human review verdict (+label+/+annotation+). +correlation_id+ + +turn_index+ group the turns of one
+# run and form a unique key so a retried run re-snapshots in place rather than duplicating training rows.
+class CreateProtegeTraces < ActiveRecord::Migration[7.2]
+  def change
+    create_table :protege_traces do |t|
+      t.string   :correlation_id
+      t.integer  :turn_index
+
+      t.string   :model, index: true
+      t.text     :settings
+
+      t.text     :request
+      t.text     :response
+
+      t.string   :label, null: false, default: 'unlabeled', index: true
+      t.text     :annotation
+      t.datetime :reviewed_at, index: true
+
+      t.timestamps
+    end
+
+    add_index :protege_traces, %i[correlation_id turn_index], unique: true, name: 'index_protege_traces_on_run_turn'
+  end
+end

data/db/migrate/20260707120000_replace_persona_active_with_archived_at.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Replace the persona +active+ boolean with an +archived_at+ timestamp — the idiomatic soft-delete shape,
+# which also records *when* a persona was archived. The model keeps +active?+/+scope :active+ as derived
+# readers over +archived_at+, so routing/scheduler/status code is unchanged.
+class ReplacePersonaActiveWithArchivedAt < ActiveRecord::Migration[8.1]
+  # Add archived_at, mark already-deactivated personas as archived-now, then drop active.
+  #
+  # @return [void]
+  def up
+    add_column :protege_personas, :archived_at, :datetime
+    execute "UPDATE protege_personas SET archived_at = CURRENT_TIMESTAMP WHERE active = #{connection.quoted_false}"
+    remove_column :protege_personas, :active
+  end
+
+  # Restore the active boolean, deactivating any archived personas, then drop archived_at.
+  #
+  # @return [void]
+  def down
+    add_column :protege_personas, :active, :boolean, null: false, default: true
+    execute "UPDATE protege_personas SET active = #{connection.quoted_false} WHERE archived_at IS NOT NULL"
+    remove_column :protege_personas, :archived_at
+  end
+end

data/db/migrate/20260708120000_add_disabled_tool_ids_to_personas.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Add +disabled_tool_ids+ to personas — the operator's subtractive tool-scoping override. A persona's
+# code-declared +tools+ grant is the ceiling of what it *may* use; this column names the ids the operator
+# has switched *off* within that grant, so scoping narrows and never widens. Stored as a JSON array in a
+# text column (SQLite has no native JSON type), matching +Message+'s recipient-list convention, and
+# defaults to an empty array so an unconfigured persona keeps its full grant.
+class AddDisabledToolIdsToPersonas < ActiveRecord::Migration[8.1]
+  # Add the JSON-array text column, non-null with an empty-array default.
+  #
+  # @return [void]
+  def up
+    add_column :protege_personas, :disabled_tool_ids, :text, null: false, default: '[]'
+  end
+
+  # Drop the column.
+  #
+  # @return [void]
+  def down
+    remove_column :protege_personas, :disabled_tool_ids
+  end
+end

data/lib/generators/protege/extension_naming.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Protege
+  module Generators
+    # Shared naming helpers for the extension scaffold generators (+tool+, +resolver+, +hook+,
+    # +provider+). Host apps name Protege extensions by a type suffix — +SendEmailTool+,
+    # +ThreadHistoryResolver+, +EventLoggerHook+, +OpenRouterProvider+ — so these helpers derive the
+    # final class and file names from whatever the developer typed, idempotently applying the suffix.
+    #
+    # The suffix is applied whether or not it was supplied, so all three of +send_email+, +SendEmail+,
+    # and +SendEmailTool+ resolve to class +SendEmailTool+ / file +send_email_tool.rb+. Pass an empty
+    # suffix (as the persona generator does) to use the name verbatim.
+    module ExtensionNaming
+      private
+
+      # The extension's class name with +suffix+ guaranteed exactly once.
+      #
+      # @param suffix [String] the type suffix to enforce (e.g. +"Tool"+), or +""+ to use as-is
+      # @return [String] the camelized class name ending in +suffix+
+      def extension_class_name(suffix)
+        return class_name if suffix.to_s.empty?
+
+        "#{class_name.sub(/#{suffix}\z/i, '')}#{suffix}"
+      end
+
+      # The extension's file name (no extension) with the snake_cased +suffix+ guaranteed exactly once.
+      #
+      # @param suffix [String] the type suffix to enforce (e.g. +"Tool"+), or +""+ to use as-is
+      # @return [String] the snake_cased file basename ending in the underscored +suffix+
+      def extension_file_name(suffix)
+        return file_name if suffix.to_s.empty?
+
+        underscored = suffix.underscore
+        "#{file_name.sub(/_?#{underscored}\z/i, '')}_#{underscored}"
+      end
+    end
+  end
+end

data/lib/generators/protege/hook/hook_generator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require_relative '../extension_naming'
+
+module Protege
+  module Generators
+    # Scaffolds a Protege hook — an event subscriber that reacts to the agent's run lifecycle — into the
+    # host app's hooks directory (+config.hooks_path+, default +app/hooks+). A hook subclasses
+    # +Protege::Hook+ and declares +on(SomeEvent) { |event| ... }+ handlers; the engine wires them onto
+    # the event bus at boot (auto-discovered, no manual registration). Handlers run isolated, so an
+    # error in one can never break inference.
+    #
+    # The +Hook+ suffix is applied for you.
+    #
+    # @example
+    #   bin/rails g protege:hook audit_log
+    class HookGenerator < Rails::Generators::NamedBase
+      include ExtensionNaming
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a Protege::Hook subclass in the configured hooks path (default app/hooks).'
+
+      # Render the hook scaffold into +config.hooks_path+.
+      #
+      # @return [void]
+      def create_hook
+        template 'hook.rb.tt', File.join(Protege.configuration.hooks_path, "#{extension_file_name('Hook')}.rb")
+      end
+    end
+  end
+end

data/lib/generators/protege/hook/templates/hook.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# <%= extension_class_name('Hook') %> — reacts to events across the agent's run lifecycle.
+#
+# Subclassing +Protege::Hook+ wires these handlers onto the event bus at boot (auto-discovered, no
+# registration). Each +on+ block receives a typed, frozen +Protege::Event+ and runs isolated — a raised
+# error is swallowed and logged, never breaking the run. Read event fields with nil-safe named readers
+# (+event.persona+, +event.tool_call+, +event.result+, +event.error+, +event.correlation_id+).
+#
+# Declare a handler with +on(EventClass) { |event| ... }+ (pass several classes to share one block).
+# Available events (all +Protege::+ constants), in fire order:
+#   InferenceStartedEvent, InferenceGeneratedEvent, InferenceCompletedEvent, InferenceFailedEvent,
+#   ToolCallsReceivedEvent, ToolCallStartedEvent, ToolCallCompletedEvent, ToolCallFailedEvent,
+#   InferenceMaxTurnsReachedEvent, InferenceChunkEvent,
+#   LoopRunEnqueuedEvent, LoopRunStartedEvent, LoopRunCompletedEvent, LoopRunFailedEvent
+#
+# Add +stateful+ (uncomment below) to reuse ONE instance per +correlation_id+ across a run, so handlers
+# can accumulate state in instance variables; the default is a fresh instance per event.
+class <%= extension_class_name('Hook') %> < Protege::Hook
+  # stateful
+
+  # TODO: replace with the events you care about.
+  on InferenceStartedEvent do |event|
+    log "inference started for persona=#{event.persona&.name} (#{event.correlation_id})"
+  end
+
+  private
+
+  # Write a line to the configured Protege logger.
+  #
+  # @param line [String] the message to log
+  # @return [void]
+  def log(line)
+    Protege.configuration.logger.info("[<%= extension_class_name('Hook') %>] #{line}")
+  end
+end

data/lib/generators/protege/install/install_generator.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+require_relative '../persona/persona_generator'
+
+module Protege
+  module Generators
+    # Bootstraps Protege into a host Rails app — the one command to go from +gem 'protege'+ to a
+    # runnable dashboard. It installs the Rails frameworks Protege depends on (Active Storage for
+    # attachments, Action Mailbox for inbound mail), writes a fully-documented initializer, mounts the
+    # engine, wires the Loop's recurring tick, and scaffolds a starter persona. The steps it cannot do
+    # safely for you — wrapping the mount in your own authentication, running migrations, setting
+    # credentials — are printed as next steps.
+    #
+    # @example
+    #   bin/rails g protege:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Install Protege into the host app: initializer, engine mount, recurring tick, and a starter persona.'
+
+      # The recurring job entry that drives the Loop scheduler — one tick a minute fires due
+      # responsibilities. Written at column zero; {#indented_tick} nests it under an environment key.
+      RECURRING_TICK = <<~YAML
+        protege_responsibility_tick:
+          class: Protege::ResponsibilityTickJob
+          schedule: every minute
+      YAML
+
+      # The recurring.yml environments the tick must run in.
+      ENVIRONMENTS = %w[production development].freeze
+
+      # Install the Rails frameworks Protege builds on: Active Storage (attachments) and Action Mailbox
+      # (inbound mail — this also creates +app/mailboxes/application_mailbox.rb+). Their migrations are
+      # copied here; Protege's own migrations load straight from the gem.
+      #
+      # @return [void]
+      def install_dependencies
+        rails_command 'active_storage:install'
+        rails_command 'action_mailbox:install'
+      end
+
+      # Write the fully-documented Protege initializer with smart, ENV-backed defaults.
+      #
+      # @return [void]
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/protege.rb'
+      end
+
+      # Mount the engine in the host's routes, with a loud reminder to wrap it in authentication — the
+      # engine ships none, so an unwrapped mount exposes the dashboard to everyone.
+      #
+      # @return [void]
+      def mount_engine
+        route <<~RUBY.chomp
+          # TODO: Protege ships no authentication — wrap this mount in your app's auth
+          #       (e.g. `authenticate :user do ... end`) before exposing the dashboard.
+          mount Protege::Engine => '/protege'
+        RUBY
+      end
+
+      # Wire the Loop's recurring tick into +config/recurring.yml+. Creates the file when absent;
+      # ensures the tick runs in both +production+ and +development+, injecting it under an existing
+      # environment key or appending a fresh block when that environment is absent (a fresh Rails app
+      # ships only a +production:+ block, so +development:+ is added). Idempotent — a second run is a
+      # no-op once the tick is present.
+      #
+      # @return [void]
+      def add_recurring_tick
+        path = 'config/recurring.yml'
+
+        if !file_exists?(path)
+          create_file path, ENVIRONMENTS.map { |env| "#{env}:\n#{indented_tick}" }.join("\n")
+        elsif !recurring_already_wired?(path)
+          ENVIRONMENTS.each { |env| add_tick_for(env, path) }
+        end
+      end
+
+      # Scaffold a starter +Agent+ persona by delegating to the persona generator (single source of
+      # truth for the persona template).
+      #
+      # @return [void]
+      def create_starter_persona
+        invoke Protege::Generators::PersonaGenerator, ['Agent']
+      end
+
+      # Print the wiring the generator can't safely automate.
+      #
+      # @return [void]
+      def print_next_steps
+        say "\n  Protege installed.", :green
+        say <<~STEPS
+
+          Next steps:
+
+            1. Run the migrations (Active Storage, Action Mailbox, and Protege's own):
+                 bin/rails db:migrate
+
+            2. WRAP THE ENGINE MOUNT in your authentication in config/routes.rb — the engine ships no
+               auth of its own. An unwrapped mount exposes the dashboard to anyone.
+
+            3. Set your provider credentials (the defaults read OpenRouter from ENV):
+                 OPENROUTER_API_KEY=sk-...   (and OPENROUTER_MODEL to pick a model)
+
+            4. Let extensions register in development by loading them eagerly — add to
+               config/environments/development.rb:
+                 config.eager_load = true
+               (tools/providers/hooks are discovered as loaded subclasses).
+
+            5. Create your first persona + email domain (dashboard, or a db/seeds.rb bootstrap) so
+               inbound mail has somewhere to route. Then boot and open /protege.
+        STEPS
+      end
+
+      private
+
+      # Whether a path exists under the destination root.
+      #
+      # @param path [String] the app-relative path
+      # @return [Boolean]
+      def file_exists?(path)
+        File.exist?(File.join(destination_root, path))
+      end
+
+      # The contents of a destination-relative file.
+      #
+      # @param path [String] the app-relative path
+      # @return [String] the file body
+      def read_destination(path)
+        File.read(File.join(destination_root, path))
+      end
+
+      # Add the tick for one environment: nest it under the env key when that key exists, or append a
+      # fresh +<env>:+ block when it doesn't (a fresh Rails app ships +production:+ but no +development:+).
+      #
+      # @param env [String] the environment name (+production+ / +development+)
+      # @param path [String] the recurring.yml path
+      # @return [void]
+      def add_tick_for(env, path)
+        env_key = /^#{env}:[ \t]*\n/
+
+        if read_destination(path).match?(env_key)
+          # gsub_file, not inject_into_file: the latter de-dupes by content and would skip the second
+          # environment (the tick block is identical), leaving development un-wired.
+          gsub_file path, env_key do |match|
+            "#{match}#{indented_tick}"
+          end
+        else
+          append_to_file path, "\n#{env}:\n#{indented_tick}"
+        end
+      end
+
+      # Whether the tick is already wired (keeps the step idempotent).
+      #
+      # @param path [String] the recurring.yml path
+      # @return [Boolean]
+      def recurring_already_wired?(path)
+        read_destination(path).include?('protege_responsibility_tick')
+      end
+
+      # The tick entry indented two spaces so it nests under a +recurring.yml+ environment key. Blank
+      # lines are left untouched.
+      #
+      # @return [String] the indented YAML block
+      def indented_tick
+        RECURRING_TICK.gsub(/^(?=.)/, '  ')
+      end
+    end
+  end
+end

data/lib/generators/protege/install/templates/initializer.rb.tt

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Protege engine configuration. Set once at boot; treated as read-only thereafter (the Orchestrator
+# snapshots a frozen copy per delivery). Every option is shown below — active ones are set to sensible,
+# ENV-backed defaults, and optional ones are commented with their engine default so the full surface is
+# visible at a glance.
+Protege.configure do |config|
+  # ── Console / dashboard ─────────────────────────────────────────────────────
+
+  # Address representing the dashboard user in local conversations; replies to it skip SMTP delivery.
+  # (default: "console@protege.local")
+  # config.console_address = 'console@protege.local'
+
+  # Brand shown in the dashboard nav header. (default: "🥚 Protege")
+  # config.nav_title = '🥚 Protege'
+
+  # ── Inference ─────────────────────────────────────────────────────────────────
+
+  # Maximum tool-calling rounds before the harness returns the last response. (default: 8)
+  # config.max_tool_turns = 8
+
+  # Symbolic id of the provider extension to run inference through; must match a registered provider's
+  # +protege_id+ (here the built-in OpenRouter's :openrouter). (default: nil)
+  config.provider_id = :openrouter
+
+  # Per-provider options, keyed by provider id — model, sampling, and credentials all live here. The
+  # built-in OpenRouter provider reads its +:openrouter+ slice: +model+/+api_key+/+base_url+ are
+  # required (they raise on first use if missing), +temperature+/+max_output_tokens+ optional. Add a key
+  # for any custom provider and read it back via +Protege.configuration.provider_options(:your_id)+.
+  config.providers = {
+    openrouter: {
+      model:    ENV.fetch('OPENROUTER_MODEL', 'anthropic/claude-sonnet-4-5'),
+      api_key:  ENV.fetch('OPENROUTER_API_KEY', nil),
+      base_url: ENV.fetch('OPENROUTER_BASE_URL', 'https://openrouter.ai/api/v1')
+      # temperature: 0.7,
+      # max_output_tokens: 4096
+    }
+  }
+
+  # ── Tracing ───────────────────────────────────────────────────────────────────
+
+  # Capture every inference turn (request + response + settings) into a durable Protege::Trace for
+  # review and fine-tuning, browsable under /protege/traces. Off by default — nothing is recorded until
+  # you opt in; multimodal turns store attachment bytes inline, so rows can be large.
+  # (default: { enabled: false })
+  # config.tracing = { enabled: true }
+
+  # ── Inbound access control ──────────────────────────────────────────────────
+
+  # Global ceiling on which senders may reach ANY persona — the committed layer of the access guardrail.
+  # Per-persona rules (managed in the dashboard) only narrow this further, never widen it. Patterns are
+  # an exact address or a single "*" wildcard. Defaults to permit-all.
+  # config.inbound_access = Protege::Gateway.build_access_policy(allow: ['*@your-company.com'])
+  # config.inbound_access = Protege::Gateway.build_access_policy(deny: ['*@spam.example'])
+
+  # ── Attachments ─────────────────────────────────────────────────────────────
+
+  # Inbound mail breaching any limit is bounced; the send_email tool refuses to attach a breaching set.
+  # Defaults: enabled, 10 MB/attachment, 10 attachments/message, 25 MB total.
+  # config.attachment_policy = Protege::Gateway.build_attachment_policy(max_bytes: 5 * 1024 * 1024)
+  # config.attachment_policy = Protege::Gateway.build_attachment_policy(enabled: false)
+
+  # ── Web tools ───────────────────────────────────────────────────────────────
+
+  # User-Agent the built-in web_search / web_fetch tools send. Defaults to a generic, unbranded browser
+  # string.
+  # config.http_user_agent = ENV.fetch('HTTP_USER_AGENT', Protege::Configuration::DEFAULT_HTTP_USER_AGENT)
+
+  # ── Extension scaffold paths ──────────────────────────────────────────────────
+
+  # Where the `bin/rails g protege:{tool,resolver,hook,persona,provider}` generators write. Defaults to
+  # the conventional app/ directories; override if you group extensions elsewhere (must stay under an
+  # autoloaded path).
+  # config.tools_path     = 'app/tools'
+  # config.resolvers_path = 'app/resolvers'
+  # config.hooks_path     = 'app/hooks'
+  # config.personas_path  = 'app/personas'
+  # config.providers_path = 'app/providers'
+
+  # ── Logging ─────────────────────────────────────────────────────────────────
+
+  # Logger for engine output; defaults to Rails.logger. Override to route to a dedicated target:
+  # config.logger = Logger.new(Rails.root.join('log/protege.log'))
+end

data/lib/generators/protege/persona/persona_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/generators/named_base'
+require_relative '../extension_naming'
+
+module Protege
+  module Generators
+    # Scaffolds a persona — the identity Protege binds an inbox to — into the host app's personas
+    # directory (+config.personas_path+, default +app/personas+). A persona is an STI subclass of
+    # +Protege::Persona+ (an ActiveRecord model); subclassing registers the subtype, and each persona
+    # declares its display name and the resolver chains that assemble context for its reply and
+    # scheduled runs.
+    #
+    # The +Persona+ suffix is applied for you, so all of +support+, +Support+, and +SupportPersona+
+    # produce class +SupportPersona+ in +support_persona.rb+.
+    #
+    # @example
+    #   bin/rails g protege:persona support
+    class PersonaGenerator < Rails::Generators::NamedBase
+      include ExtensionNaming
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Scaffold a Protege::Persona subclass in the configured personas path (default app/personas).'
+
+      # Render the persona scaffold into +config.personas_path+.
+      #
+      # @return [void]
+      def create_persona
+        template 'persona.rb.tt',
+                 File.join(Protege.configuration.personas_path, "#{extension_file_name('Persona')}.rb")
+      end
+    end
+  end
+end

data/lib/generators/protege/persona/templates/persona.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# <%= extension_class_name('Persona') %> — a persona: the identity Protege binds an inbox to.
+#
+# Subclassing +Protege::Persona+ (an STI ActiveRecord model) registers this subtype. Create the row in
+# the dashboard (or a seed) to give it a +name+, +email_address+, and +instructions+ (its editable
+# system prompt); inbound mail to that address routes here, and outbound replies are sent as it.
+#
+# The two chains below assemble the context sent to the model. Engine built-in resolvers are named by
+# their flat +Protege::+ constant; host-app resolvers (see <%= Protege.configuration.resolvers_path %>/) by their own top-level constant.
+class <%= extension_class_name('Persona') %> < Protege::Persona
+  # Human-friendly label shown for this persona in the dashboard, logs, and tooling.
+  self.display_name = '<%= extension_class_name('Persona').titleize %>'
+
+  # Context assembled before every reply to inbound mail. +Protege::LoadTextResolver+ supplies this
+  # persona's dashboard-editable +instructions+ as the system prompt; +Protege::ThreadHistoryResolver+
+  # replays the conversation so far. Insert your own resolvers between them (e.g. to inject records,
+  # summaries, or retrieved facts).
+  message_resolvers do |chain|
+    chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.persona.instructions }
+    chain.use Protege::ThreadHistoryResolver
+  end
+
+  # Context assembled for a scheduled run (the Loop layer). There is no inbound thread, so the chain is
+  # just identity: the persona's +instructions+ as the system prompt and the responsibility's own
+  # prompt as the opening user message. Add task-specific resolvers here if a responsibility needs more.
+  responsibility_resolvers do |chain|
+    chain.use(Protege::LoadTextResolver, role: :system) { |ctx| ctx.persona.instructions }
+    chain.use(Protege::LoadTextResolver, role: :user)   { |ctx| ctx.responsibility.instructions }
+  end
+end

data/lib/generators/protege/postfix/postfix_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module Protege
+  module Generators
+    # Vendors the self-hosted Postfix + OpenDKIM mail-server deploy files into the host application.
+    #
+    # Self-hosting mail needs a Docker image that runs Postfix (MTA) and OpenDKIM (DKIM) for the agent
+    # domain. Those build files ship inside the gem; this generator copies them into the host's
+    # +deploy/mail/+ so the developer can build, publish, and run the image (e.g. as a Kamal accessory).
+    # It also drops adaptable host-wiring references (a Kamal accessory snippet, an example CI workflow,
+    # and a deploy guide), then prints the next steps.
+    #
+    # Files are copied **verbatim** (never ERB-templated): +main.cf+/+KeyTable+/+SigningTable+ carry a
+    # +__MAIL_DOMAIN__+ placeholder and the scripts use shell +${VAR}+ interpolation — all substituted
+    # at container runtime by +entrypoint.sh+, not at generate time.
+    #
+    # @example
+    #   bin/rails g protege:postfix
+    class PostfixGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Copy the self-hosted Postfix + OpenDKIM mail-server deploy files into deploy/mail/.'
+
+      # Copy the container build files + in-repo references (README, MAIL.md, Kamal snippet) verbatim.
+      #
+      # @return [void]
+      def copy_mail_server_files
+        directory 'deploy/mail', 'deploy/mail'
+      end
+
+      # Copy the example CI workflow that builds and publishes the image.
+      #
+      # @return [void]
+      def copy_ci_workflow
+        copy_file 'github/workflows/build-mail-image.example.yml',
+                  '.github/workflows/build-mail-image.example.yml'
+      end
+
+      # Print the host-side wiring the generator can't do for you (deployment-specific).
+      #
+      # @return [void]
+      def print_next_steps
+        say "\n  Self-hosted mail files written to deploy/mail/.", :green
+        say <<~STEPS
+
+          Next steps (see deploy/mail/MAIL.md for the full guide):
+
+            1. Build + publish the image:
+                 docker build --platform linux/amd64 -t YOUR_REGISTRY/protege-mail:latest deploy/mail
+                 docker push YOUR_REGISTRY/protege-mail:latest
+               (or rename .github/workflows/build-mail-image.example.yml to build it in CI)
+
+            2. Run it as your MTA — merge deploy/mail/kamal-accessory.example.yml into config/deploy.yml.
+               The only secret is RAILS_INBOUND_EMAIL_PASSWORD; there is NO DKIM key secret — the app
+               pushes each domain's key to the MTA when you add it (and via the console "Sync now" button).
+               Keep the protege_mail_provision volume so the pushed keys survive restarts.
+
+            3. Point the app at it (config/environments/production.rb + deploy.yml app env):
+                 config.action_mailbox.ingress = :relay
+                 config.action_mailer.smtp_settings = { address: ENV.fetch("MAIL_RELAY_HOST", "protege-mail"),
+                                                         port: 25, authentication: nil, enable_starttls_auto: false }
+               Set MAIL_RELAY_HOST: protege-mail in the app service's env — the app pushes provisioning
+               there, and its presence puts the console in self-hosted mode.
+
+            4. Set up PTR/reverse DNS, open inbound TCP 25, request an outbound-25 unblock if needed,
+               then add each agent domain in the dashboard (Domains → New) and publish the SPF/DKIM/DMARC
+               + MX records it shows.
+        STEPS
+      end
+    end
+  end
+end

data/lib/generators/protege/postfix/templates/deploy/mail/Dockerfile

@@ -0,0 +1,43 @@
+# Self-hosted MTA for Protege: Postfix (SMTP send + receive) + OpenDKIM (sign + verify) + OpenDMARC and
+# policyd-spf (inbound SPF/DKIM/DMARC enforcement).
+#
+# Runs as the Kamal `mail` accessory (see workspace/config/deploy.yml). It owns port 25 on the VPS:
+#   - inbound: checks SPF (policyd-spf) + DKIM (OpenDKIM) + DMARC (OpenDMARC), rejecting spoofed/failing
+#     mail at SMTP, then pipes each surviving message to the app's relay ingress.
+#   - outbound: accepts mail from the app container (Kamal network), OpenDKIM-signs it, delivers to
+#     the recipient's MX directly (no relay provider). Our own outbound skips the inbound checks.
+#
+# Build + push (Kamal accessories pull a prebuilt image, they do not build one):
+#   docker build --platform linux/amd64 -t ghcr.io/sebscholl/protege-mail:latest workspace/deploy/mail
+#   docker push ghcr.io/sebscholl/protege-mail:latest
+FROM debian:bookworm-slim
+
+# postfix: MTA. opendkim/opendkim-tools: DKIM milter. opendmarc: DMARC milter.
+# postfix-policyd-spf-python: SPF policy service. rsyslog: Postfix logs via syslog; we tail it to
+# stdout so `kamal accessory logs mail` shows mail.log. curl/ca-certificates: inbound relay POST + TLS.
+RUN apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+       postfix opendkim opendkim-tools opendmarc postfix-policyd-spf-python \
+       rsyslog curl ca-certificates openssl \
+  && rm -rf /var/lib/apt/lists/*
+
+# Postfix + OpenDKIM + OpenDMARC + policyd-spf configuration. main.cf drives Postfix; opendkim.conf +
+# the tables drive signing/verifying; opendmarc.conf drives DMARC enforcement; policyd-spf.conf drives
+# SPF. The actionmailbox pipe and the policyd-spf spawn service are appended to the stock master.cf at
+# runtime (postconf -M) so we keep the distro's standard services. The entrypoint fills in the runtime
+# bits (MAIL_DOMAIN, the DMARC reject toggle) first, then provision.py writes the per-domain DKIM keys +
+# tables from the manifest the app pushes (KeyTable/SigningTable ship as generated-at-runtime stubs).
+# python3 for provision.py is already present (pulled in by postfix-policyd-spf-python).
+COPY main.cf /etc/postfix/main.cf
+COPY opendkim.conf /etc/opendkim.conf
+COPY KeyTable SigningTable TrustedHosts /etc/opendkim/
+COPY opendmarc.conf /etc/opendmarc.conf
+COPY opendmarc.ignore.hosts /etc/opendmarc/ignore.hosts
+COPY policyd-spf.conf /etc/postfix-policyd-spf-python/policyd-spf.conf
+COPY relay-to-app.sh /usr/local/bin/relay-to-app.sh
+COPY provision.py /usr/local/bin/provision.py
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/relay-to-app.sh /usr/local/bin/provision.py /usr/local/bin/entrypoint.sh
+
+EXPOSE 25
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

data/lib/generators/protege/postfix/templates/deploy/mail/KeyTable

@@ -0,0 +1,3 @@
+# generated at runtime by provision.py — do not edit
+# One line per domain, written from the manifest the Rails app pushes:
+#   <selector>._domainkey.<domain> <domain>:<selector>:/var/lib/protege-mail/keys/<domain>/<selector>.private