protege 0.1.0.alpha.2 → 0.1.0.alpha.7

data/app/views/protege/responsibilities/_responsibility_sidebar_item.html.slim

@@ -1,5 +1,5 @@
 = sidebar_item(responsibility.name, responsibility_path(responsibility),
     detail: responsibility_status(responsibility),
-    subtitle: "#{responsibility.persona.name} · #{responsibility.schedule}",
+    subtitle: "#{responsibility.agent.name} · #{responsibility.schedule}",
     active: local_assigns[:active],
     id: dom_id(responsibility))

data/app/views/protege/responsibilities/new.html.slim

@@ -2,6 +2,6 @@
   = render "sidebar"
 
 = page_container do
-  = page_header("New responsibility", "A scheduled duty a persona carries out on a cron schedule.")
+  = page_header("New responsibility", "A scheduled duty an agent carries out on a cron schedule.")
 
   = card { render "form", responsibility: @responsibility }

data/app/views/protege/responsibilities/show.html.slim

@@ -2,13 +2,13 @@
   = render "sidebar", current: @responsibility
 
 = page_container do
-  = page_header(@responsibility.name, "#{@responsibility.persona.name} · #{@responsibility.schedule}") do
+  = page_header(@responsibility.name, "#{@responsibility.agent.name} · #{@responsibility.schedule}") do
     div
       = ui_link("Edit", edit_responsibility_path(@responsibility), class: 'px-3')
       = inline_button("Run now", responsibility_runs_path, params: { responsibility_run: { responsibility_id: @responsibility.id } })
 
   .space-y-4
-    = info_card("Schedule", { "Cron" => @responsibility.schedule, "Persona" => @responsibility.persona.name, "Active" => (@responsibility.active? ? "Yes" : "No") })
+    = info_card("Schedule", { "Cron" => @responsibility.schedule, "Agent" => @responsibility.agent.name, "Active" => (@responsibility.active? ? "Yes" : "No") })
 
     = card do
       = heading_2("Instructions")

data/app/views/protege/responsibility_runs/show.html.slim

@@ -1,5 +1,5 @@
 = page_container do
-  = page_header("Run · #{@responsibility.name}", @responsibility.persona.name) do
+  = page_header("Run · #{@responsibility.name}", @responsibility.agent.name) do
     = ui_link("Back", responsibility_path(@responsibility))
 
   .space-y-4

data/app/views/protege/shared/_header.html.slim

@@ -4,8 +4,9 @@ header class="flex h-14 flex-shrink-0 items-center justify-between px-5" style="
 
     nav class="flex items-center gap-1"
       = nav_item("Inbox", protege.threads_path, request.path)
+      = nav_item("Agents", protege.agents_path, request.path)
+      = nav_item("Toolkits", protege.toolkits_path, request.path)
       = nav_item("Responsibilities", protege.responsibilities_path, request.path)
-      = nav_item("Personas", protege.personas_path, request.path)
       = nav_item("Domains", protege.email_domains_path, request.path)
       = nav_item("Traces", protege.traces_path, request.path)
 

data/app/views/protege/shared/_hotkeys.html.slim

@@ -3,19 +3,21 @@
 /
 / Registry — the single source of truth for app-wide combos. Each is a hidden link keys.js activates on
 / its combo; it navigates via the same route helper the visible UI uses, so a global command works from
-/ anywhere, independent of what's on screen. Nav combos are numbered by position (1..5, left to right)
+/ anywhere, independent of what's on screen. Nav combos are numbered by position (1..6, left to right)
 / rather than by initial — the "go to the Nth section" convention (⌘1..9 in browsers/editors). Rendered
 / after the page body, so a page-local hotkey reusing a combo is matched first and shadows the global one.
 div hidden=true aria-hidden="true"
   = link_to "Documentation",      'https://docs.protege.bot',      data: { hotkey: "g 0" }, target: '_blank'
   = link_to "Inbox",              protege.threads_path,            data: { hotkey: "g 1" }
-  = link_to "Responsibilities",   protege.responsibilities_path,   data: { hotkey: "g 2" }
-  = link_to "Personas",           protege.personas_path,           data: { hotkey: "g 3" }
-  = link_to "Domains",            protege.email_domains_path,      data: { hotkey: "g 4" }
-  = link_to "Traces",             protege.traces_path,             data: { hotkey: "g 5" }
+  = link_to "Agents",             protege.agents_path,             data: { hotkey: "g 2" }
+  = link_to "Toolkits",           protege.toolkits_path,           data: { hotkey: "g 3" }
+  = link_to "Responsibilities",   protege.responsibilities_path,   data: { hotkey: "g 4" }
+  = link_to "Domains",            protege.email_domains_path,      data: { hotkey: "g 5" }
+  = link_to "Traces",             protege.traces_path,             data: { hotkey: "g 6" }
   = link_to "New Thread",         protege.new_thread_path,         data: { hotkey: "g c" }
+  = link_to "New Agent",          protege.new_agent_path,          data: { hotkey: "g a" }
+  = link_to "New Toolkit",        protege.new_toolkit_path,        data: { hotkey: "g k" }
   = link_to "New Responsibility", protege.new_responsibility_path, data: { hotkey: "g r" }
-  = link_to "New Persona",        protege.new_persona_path,        data: { hotkey: "g p" }
   = link_to "New Email Domain",   protege.new_email_domain_path,   data: { hotkey: "g d" }
 
 / Help overlay, opened with "?" or the header's "?" button (keys.js just toggles it open/closed). This
@@ -26,16 +28,18 @@ div hidden=true aria-hidden="true"
   .mt-3.space-y-1
     = hotkey_section("Go to")
     = hotkey_row("Inbox", "g", "1")
-    = hotkey_row("Responsibilities", "g", "2")
-    = hotkey_row("Personas", "g", "3")
-    = hotkey_row("Domains", "g", "4")
-    = hotkey_row("Traces", "g", "5")
+    = hotkey_row("Agents", "g", "2")
+    = hotkey_row("Toolkits", "g", "3")
+    = hotkey_row("Responsibilities", "g", "4")
+    = hotkey_row("Domains", "g", "5")
+    = hotkey_row("Traces", "g", "6")
     = hotkey_row("Documentation", "g", "0")
 
     = hotkey_section("Create")
     = hotkey_row("New thread", "g", "c")
+    = hotkey_row("New agent", "g", "a")
+    = hotkey_row("New toolkit", "g", "k")
     = hotkey_row("New responsibility", "g", "r")
-    = hotkey_row("New persona", "g", "p")
     = hotkey_row("New email domain", "g", "d")
 
     = hotkey_section("General")

data/app/views/protege/threads/new.html.slim

@@ -2,11 +2,11 @@
   = render "protege/threads/sidebar", threads: inbox_threads
 
 = page_container do
-  = page_header("New message", "Send a message to a persona to start a thread.")
+  = page_header("New message", "Send a message to an agent to start a thread.")
 
   = card do
     = form_with url: threads_path, scope: :thread, class: "space-y-5", multipart: true do |f|
-      = form_select(f, :persona_id, available_persona_options, label: "To", prompt: "Select persona...")
+      = form_select(f, :agent_id, available_agent_options, label: "To", prompt: "Select agent...")
 
       = form_field(f, :subject, label: "Subject", placeholder: "Subject")
 

data/app/views/protege/toolkits/_form.html.slim

@@ -0,0 +1,13 @@
+= form_with model: toolkit, class: "space-y-5" do |f|
+  = form_errors(toolkit)
+
+  = form_field(f, :name, placeholder: "e.g. Finance")
+
+  = form_text_area(f, :description, label: "Description", rows: 3, hint: "What this toolkit is for — shown only in the dashboard.")
+
+  - tool_id = ->(entry) { entry.id.to_s }
+  = form_checklist(f, :member_tool_ids, toolkit_tool_options, label: "Tools", value: tool_id, text: :display_name, description: :summary, hint: "The tools this toolkit bundles. Who may use them is set per agent when you attach it.")
+
+  .flex.items-center.gap-3.pt-2
+    = button("Save toolkit", type: :submit)
+    = ui_link("Cancel", toolkits_path)

data/app/views/protege/toolkits/_sidebar.html.slim

@@ -0,0 +1,11 @@
+- pagy, toolkits = paginate(all_toolkits)
+
+= sidebar_content do
+  = sidebar_header("Toolkits (#{pagy.count})", new_path: new_toolkit_path)
+
+  = sidebar_stream("protege:toolkits", pagy: pagy)
+
+  = sidebar_body(toolkits, empty: "No toolkits yet", id: "toolkits_list") do |toolkit|
+    = render "toolkit_sidebar_item", toolkit: toolkit, active: local_assigns[:current] == toolkit
+
+  = sidebar_pagination(pagy)

data/app/views/protege/toolkits/_toolkit_sidebar_item.html.slim

@@ -0,0 +1,5 @@
+= sidebar_item(toolkit.name, toolkit_path(toolkit),
+    subtitle: toolkit_tool_count_label(toolkit),
+    detail: (badge("System", :yellow, size: :sm) if toolkit.system?),
+    active: local_assigns[:active],
+    id: dom_id(toolkit))

data/app/views/protege/toolkits/edit.html.slim

@@ -0,0 +1,7 @@
+- content_for :sidebar do
+  = render "sidebar", current: @toolkit
+
+= page_container do
+  = page_header("Edit #{@toolkit.name}")
+
+  = card { render "form", toolkit: @toolkit }

data/app/views/protege/toolkits/index.html.slim

@@ -0,0 +1,6 @@
+- content_for :sidebar do
+  = render "sidebar"
+
+= page_empty do
+  | Select a toolkit from the sidebar, or  
+  = ui_link("create a new one.", new_toolkit_path)

data/app/views/protege/toolkits/new.html.slim

@@ -0,0 +1,7 @@
+- content_for :sidebar do
+  = render "sidebar"
+
+= page_container do
+  = page_header("New toolkit", "A bundle of tools exposed to an agent only for senders that pass its gate.")
+
+  = card { render "form", toolkit: @toolkit }

data/app/views/protege/toolkits/show.html.slim

@@ -0,0 +1,13 @@
+- content_for :sidebar do
+  = render "sidebar", current: @toolkit
+
+= page_container do
+  = page_header(@toolkit.name, @toolkit.description) do
+    div
+      = ui_link("Edit", edit_toolkit_path(@toolkit), class: "px-3")
+      - unless @toolkit.system?
+        = destructive_link("Delete", toolkit_path(@toolkit), confirm: "Delete this toolkit?", method: :delete)
+
+  .space-y-4
+    = info_card("Toolkit", toolkit_overview(@toolkit))
+    = hint("This toolkit is a reusable set of tools. Who may use them is decided per agent — attach it on an agent's page to set its sender gate.")

data/config/routes.rb

@@ -18,13 +18,24 @@ Protege::Engine.routes.draw do
   resources :responsibilities
   resources :responsibility_runs
 
+  resources :toolkits
+
+  # A grant (agent↔toolkit) is split across two controllers so nesting never goes two deep. The
+  # *nested* Agents::AgentToolkitsController lists an agent's grants and attaches/detaches them (in
+  # the agent's scope); the *top-level* AgentToolkitsController manages a created grant on its own
+  # page, where its sender-gate rules nest one level deep (like access_rules under an agent).
+  resources :agent_toolkits do
+    resources :agent_toolkit_rules
+  end
+
   resources :threads do
     resource :reply
   end
 
-  resources :personas do
+  resources :agents do
     resource :archive
     resources :access_rules
+    resources :agent_toolkits, module: :agents
   end
 
   resources :email_domains do

data/db/migrate/20260707120000_replace_persona_active_with_archived_at.rb

@@ -3,7 +3,7 @@
 # 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]
+class ReplacePersonaActiveWithArchivedAt < ActiveRecord::Migration[7.2]
   # Add archived_at, mark already-deactivated personas as archived-now, then drop active.
   #
   # @return [void]

data/db/migrate/20260708120000_add_disabled_tool_ids_to_personas.rb

@@ -5,7 +5,7 @@
 # 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]
+class AddDisabledToolIdsToPersonas < ActiveRecord::Migration[7.2]
   # Add the JSON-array text column, non-null with an empty-array default.
   #
   # @return [void]

data/db/migrate/20260728140000_scope_message_and_thread_uniqueness_per_persona.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Scopes inbound-mail uniqueness per persona, so one email addressed to several proteges can be handled
+# by each of them independently. Previously +thread_id+ and +message_id+ were globally unique, which
+# assumed exactly one persona per inbound message: the second persona's thread/message insert collided on
+# the global index. Making both unique per +persona_id+ lets every addressed persona own its own thread
+# and message for the same RFC Message-ID, while still keeping a single persona's retries idempotent.
+class ScopeMessageAndThreadUniquenessPerPersona < ActiveRecord::Migration[7.2]
+  def change
+    remove_index :protege_email_threads, column: :thread_id, unique: true
+    add_index    :protege_email_threads, %i[persona_id thread_id], unique: true
+
+    remove_index :protege_messages, column: :message_id, unique: true
+    add_index    :protege_messages, %i[persona_id message_id], unique: true
+  end
+end

data/db/migrate/20260812000001_create_protege_toolkits.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Creates the toolkit binding tables — the first "Binding" of the extension framework. A toolkit is a
+# global, dashboard-managed, reusable bundle of tools (referenced by their manifest ids, stored as a JSON
+# id list like +disabled_tool_ids+) — nothing more. Permission lives on the *attachment*: a
+# +protege_persona_toolkits+ row gives a toolkit to one persona and carries that grant's sender gate
+# (child +persona_toolkit_rules+ rows, kind + pattern, mirroring +AccessRule+) plus +allow_proactive+ (may
+# these tools run on that persona's scheduled, senderless runs?). So the same toolkit attached to two
+# personas can be gated differently, with no tool-list duplication.
+class CreateProtegeToolkits < ActiveRecord::Migration[7.2]
+  def change
+    create_table :protege_toolkits do |t|
+      t.string :name, null: false, index: { unique: true }
+      t.text   :description
+      t.text   :member_tool_ids, null: false, default: '[]'
+
+      t.timestamps
+    end
+
+    create_table :protege_persona_toolkits do |t|
+      t.references :persona,         null: false, foreign_key: { to_table: :protege_personas }
+      t.references :toolkit,         null: false, foreign_key: { to_table: :protege_toolkits }
+      t.boolean    :allow_proactive, null: false, default: false
+
+      t.timestamps
+    end
+    add_index :protege_persona_toolkits, %i[persona_id toolkit_id], unique: true
+
+    create_table :protege_persona_toolkit_rules do |t|
+      t.references :persona_toolkit, null: false, foreign_key: { to_table: :protege_persona_toolkits }
+      t.string     :kind,            null: false
+      t.string     :pattern,         null: false
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260815000001_remove_disabled_tool_ids_from_personas.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Remove +disabled_tool_ids+ from personas. Tool access no longer flows through a per-persona ceiling (a
+# code-declared +tools+ grant minus this disable list); a persona's tools now come entirely from the
+# toolkits attached to it, gated per attachment (see +Protege::Toolable+ / +PersonaToolkit+). The
+# subtractive override this column backed no longer exists, so the column is dropped.
+class RemoveDisabledToolIdsFromPersonas < ActiveRecord::Migration[7.2]
+  # Drop the column.
+  #
+  # @return [void]
+  def up
+    remove_column :protege_personas, :disabled_tool_ids
+  end
+
+  # Restore the JSON-array text column, non-null with an empty-array default.
+  #
+  # @return [void]
+  def down
+    add_column :protege_personas, :disabled_tool_ids, :text, null: false, default: '[]'
+  end
+end

data/db/migrate/20260815000002_add_key_to_protege_toolkits.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Add a stable +key+ to toolkits so the engine can identify its *system* toolkits — the auto-maintained
+# "All Tools" (+all_tools+) and the auto-attached "Default Tools" (+default_tools+) — independently of
+# their display name (which operators may rename). User-created toolkits leave +key+ null; a unique index
+# (SQLite allows multiple NULLs) keeps at most one toolkit per system key.
+#
+# Installs seeded before system toolkits existed already have an "All Tools" toolkit (created by the old
+# host seed). Adopt it as the keyed system toolkit here, so the sync updates that record in place rather
+# than colliding on its unique name.
+class AddKeyToProtegeToolkits < ActiveRecord::Migration[7.2]
+  def up
+    add_column :protege_toolkits, :key, :string
+    add_index  :protege_toolkits, :key, unique: true
+
+    execute("UPDATE protege_toolkits SET key = 'all_tools' WHERE name = 'All Tools' AND key IS NULL")
+  end
+
+  def down
+    remove_column :protege_toolkits, :key
+  end
+end

data/db/migrate/20260815100000_rename_personas_to_agents.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Rename the Persona concept to Agent across the schema — the industry has settled on "agent" for the
+# addressable actor, and the code now follows suit (+Protege::Agent+, +AgentToolkit+, …). Pure renames,
+# so existing installs transition in place with their data intact: the three persona tables become agent
+# tables, and every +persona_id+ foreign key becomes +agent_id+. Rails renames the conventionally-named
+# indexes along with each table/column, and SQLite keeps foreign-key references pointed at the renamed
+# tables. Earlier migrations keep their historical persona names — on a fresh install they run first and
+# this migration renames their output.
+class RenamePersonasToAgents < ActiveRecord::Migration[7.2]
+  def change
+    rename_table :protege_personas, :protege_agents
+    rename_table :protege_persona_toolkits, :protege_agent_toolkits
+    rename_table :protege_persona_toolkit_rules, :protege_agent_toolkit_rules
+
+    rename_column :protege_email_threads, :persona_id, :agent_id
+    rename_column :protege_messages, :persona_id, :agent_id
+    rename_column :protege_access_rules, :persona_id, :agent_id
+    rename_column :protege_responsibilities, :persona_id, :agent_id
+    rename_column :protege_tool_uses, :persona_id, :agent_id
+    rename_column :protege_agent_toolkits, :persona_id, :agent_id
+    rename_column :protege_agent_toolkit_rules, :persona_toolkit_id, :agent_toolkit_id
+  end
+end

data/lib/generators/protege/agent/agent_generator.rb

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

data/lib/generators/protege/{persona/templates/persona.rb.tt → agent/templates/agent.rb.tt}

@@ -1,31 +1,31 @@
 # frozen_string_literal: true
 
-# <%= extension_class_name('Persona') %> — a persona: the identity Protege binds an inbox to.
+# <%= extension_class_name('Agent') %> — an agent: the identity Protege binds an inbox to.
 #
-# Subclassing +Protege::Persona+ (an STI ActiveRecord model) registers this subtype. Create the row in
+# Subclassing +Protege::Agent+ (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 %>'
+class <%= extension_class_name('Agent') %> < Protege::Agent
+  # Human-friendly label shown for this agent in the dashboard, logs, and tooling.
+  self.display_name = '<%= extension_class_name('Agent').titleize %>'
 
   # Context assembled before every reply to inbound mail. +Protege::LoadTextResolver+ supplies this
-  # persona's dashboard-editable +instructions+ as the system prompt; +Protege::ThreadHistoryResolver+
+  # agent'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::LoadTextResolver, role: :system) { |ctx| ctx.agent.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
+  # just identity: the agent'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: :system) { |ctx| ctx.agent.instructions }
     chain.use(Protege::LoadTextResolver, role: :user)   { |ctx| ctx.responsibility.instructions }
   end
 end

data/lib/generators/protege/extension_naming.rb

@@ -9,7 +9,7 @@ module Protege
     #
     # 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.
+    # suffix (as the agent generator does) to use the name verbatim.
     module ExtensionNaming
       private
 

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

@@ -5,7 +5,7 @@
 # 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+).
+# (+event.agent+, +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:
@@ -21,7 +21,7 @@ class <%= extension_class_name('Hook') %> < Protege::Hook
 
   # TODO: replace with the events you care about.
   on InferenceStartedEvent do |event|
-    log "inference started for persona=#{event.persona&.name} (#{event.correlation_id})"
+    log "inference started for agent=#{event.agent&.name} (#{event.correlation_id})"
   end
 
   private

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

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 require 'rails/generators/base'
-require_relative '../persona/persona_generator'
+require_relative '../agent/agent_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
+    # engine, wires the Loop's recurring tick, and scaffolds a starter agent. The steps it cannot do
     # safely for you — wrapping the mount in your own authentication, running migrations, setting
     # credentials — are printed as next steps.
     #
@@ -17,7 +17,7 @@ module Protege
     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.'
+      desc 'Install Protege into the host app: initializer, engine mount, recurring tick, and a starter agent.'
 
       # 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.
@@ -76,12 +76,12 @@ module Protege
         end
       end
 
-      # Scaffold a starter +Agent+ persona by delegating to the persona generator (single source of
-      # truth for the persona template).
+      # Scaffold a starter +ExecutiveAgent+ by delegating to the agent generator (single source of
+      # truth for the agent template).
       #
       # @return [void]
-      def create_starter_persona
-        invoke Protege::Generators::PersonaGenerator, ['Agent']
+      def create_starter_agent
+        invoke Protege::Generators::AgentGenerator, ['Executive']
       end
 
       # Print the wiring the generator can't safely automate.
@@ -96,18 +96,23 @@ module Protege
             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
+            2. Sync the system toolkits (creates "All Tools" and "Default Tools"; agents you create
+               afterwards auto-attach Default Tools, so they can reply out of the box). Run it on
+               every deploy, after db:migrate:
+                 bin/rails protege:toolkits:sync
+
+            3. 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):
+            4. 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
+            5. 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
+            6. Create your first agent + email domain (dashboard, or a db/seeds.rb bootstrap) so
                inbound mail has somewhere to route. Then boot and open /protege.
         STEPS
       end

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

@@ -16,8 +16,13 @@ Protege.configure do |config|
 
   # ── Inference ─────────────────────────────────────────────────────────────────
 
-  # Maximum tool-calling rounds before the harness returns the last response. (default: 8)
-  # config.max_tool_turns = 8
+  # Maximum tool-calling rounds before the harness returns the last response. (default: 100)
+  # config.max_tool_turns = 100
+
+  # X-Protege-Recursion hop count at which inbound mail is silently dropped — bounds agent-to-agent
+  # reply loops. A human replying anywhere resets the chain (mail clients don't echo the header).
+  # (default: 50)
+  # config.recursion_limit = 50
 
   # 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)
@@ -47,8 +52,8 @@ Protege.configure do |config|
 
   # ── 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
+  # Global ceiling on which senders may reach ANY agent — the committed layer of the access guardrail.
+  # Per-agent 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'])
@@ -68,15 +73,21 @@ Protege.configure do |config|
 
   # ── Extension scaffold paths ──────────────────────────────────────────────────
 
-  # Where the `bin/rails g protege:{tool,resolver,hook,persona,provider}` generators write. Defaults to
+  # Where the `bin/rails g protege:{tool,resolver,hook,agent,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.agents_path  = 'app/agents'
   # config.providers_path = 'app/providers'
 
+  # ── Failure alerts ──────────────────────────────────────────────────────────
+
+  # Email the platform operator when an inference run fails (sent via Action Mailer, outside the
+  # agent's own mail flow). Off by default; no alert is sent until `to:` is set.
+  # config.failure_alerts = { to: ['ops@example.com'], from: 'alerts@your-domain.com' }
+
   # ── Logging ─────────────────────────────────────────────────────────────────
 
   # Logger for engine output; defaults to Rails.logger. Override to route to a dedicated target:

data/lib/generators/protege/postfix/templates/deploy/mail/MAIL.md

@@ -101,7 +101,7 @@ Pre-stage the TXT records anytime. Do **not** change the MX until you cut over (
 2. Deploy the app and **boot the accessory** (Kamal `deploy` does not manage accessories):
    `kamal accessory boot mail`.
 3. Point the **MX** at `agent.example.com` (priority 10). Inbound now arrives at your box.
-4. Validate: `kamal accessory logs mail`; email the persona from Gmail → reply lands with
+4. Validate: `kamal accessory logs mail`; email the agent from Gmail → reply lands with
    **SPF/DKIM/DMARC = pass** ("Show original"). Score at [mail-tester.com](https://www.mail-tester.com)
    and iterate on reputation.
 
@@ -126,7 +126,7 @@ Our own outbound (the app container, on RFC1918) skips all three — only remote
   first-run window: deploy with `monitor`, watch `kamal accessory logs mail` for `dmarc=fail` on
   legitimate senders, then switch to `enforce` and redeploy (no image rebuild needed).
 
-To verify: from a Gmail account, email the persona and confirm a normal message is delivered with
+To verify: from a Gmail account, email the agent and confirm a normal message is delivered with
 `dmarc=pass`; a spoofing attempt against a `p=reject` domain is refused at SMTP (visible in the logs).
 
 ## Rollback